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Abstract 


This  report  details  the  implementation  of  an  experimental  platform  that  will  be  used  in  order  to  study 
how  humans  understand  complex  systems  /  situations.  It  implements  a  microworld  as  well  as  a  scenario 
building  tool  that  facilitates  the  development  of  a  range  of  scenarios  using  a  common  platform.  A  user 
guide  of  the  platform  is  first  provided  in  this  report.  It  describes  how  to  use  the  user  interface  that 
enables  interaction  with  the  situation  and  how  to  configure  its  various  parameters.  The  scenario 
building  tool  is  also  presented.  It  allows  adding  data  structures  to  a  scenario  that  will  enable/disable 
associated  functionalities.  It  exploits  a  simulator  that  was  built  as  part  of  the  IMAGE  project  in  order  to 
simulate  system  dynamics,  the  formalism  that  was  chosen  to  represent  a  complex  situation.  Finally, 
additional  technical  details  are  provided  in  the  appendices. 


R0suml2] 


Ce  rapport  dScrit  IBImplantation  d&ine  plateforme  exp0rimentale  visant  0  0tudier  la  mani0re  dont  les 
humains  arrivent  0  comprendre  des  syst0mes  /  situations  complexes.  Le  logiciel  d0velopp0  implante  un 
micromonde  ainsi  quHLin  outil  qui  facilite  le  d0veloppement  de  sc0narios  divers  0  IKiide  dime  plateforme 
unique.  Ce  rapport  fournit  tout  dabord  un  guide  de  ISLitilisateur  de  la  plateforme  exp0rimentale.  II  d0crit 
comment  I  Interface  utilisateur  devrait  0tre  utilis0e  ainsi  que  la  mani0re  de  configurer  les  diff0rents 
param0tres  qui  rendent  cette  plateforme  si  flexible.  LSbutil  de  g0n0ration  de  sc0narios  est  par  la  suite 
d0taill0.  II  permet  IHjout  de  structures  de  donn0es  dans  un  sc0nario  qui  viendront  activer/d0sactiver  les 
fonctionnalit0s  associ0es.  Cet  outil  exploite  un  simulateur  d0velopp0  dans  le  cadre  du  projet  IMAGE,  afin 
de  simuler  la  dynamique  des  syst0mes,  le  formalisme  choisi  afin  de  simuler  des  situations  complexes. 
Finalement,  plusieurs  d0tails  techniques  sont  fournis  en  annexe. 
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Executive  Summary 


The  current  experimental  platform  will  allow  experimenters  to  study  how  humans  come  to  understand 
complex  systems  /  situations.  Participants  need  to  complete  mandates  that  involve  one  or  more  human 
participants  who  have  to  make  decisions  on  possible  interventions  in  order  to  steer  the  system  (or 
situation)  to  a  desired  state.  For  that  purpose,  a  highly  configurable  and  generic  user  interface  was  built. 
It  allows  for  a  participant  to  perceive  the  current  situation,  inspect  influence  diagrams  describing  the 
known  cause-effect  relationships  in  the  system,  make  predictions  about  what  the  situation  will  look  like 
in  the  next  turn,  make  decisions  by  distributing  action  points  on  interventions,  reading  information 
snippets  and  taking  notes  on  what  the  current  strategy  is.  In  addition  to  the  latter  content,  the  user 
interface  provides  useful  feedback  at  the  end  of  a  turn  and  at  the  end  of  a  mandate  and  displaying 
information  about  the  current  state  on  each  turn.  Several  participants  at  a  time  can  contribute  to  the 
evolution  of  a  simulated  situation,  either  in  collaboration  or  in  competition.  The  present  document 
constitutes  a  complete  user  guide  on  how  to  use  the  platform  effectively. 

This  report  first  introduces  how  to  use  the  user  interface  associated  to  the  experimental  platform.  It  was 
built  in  such  a  way  that  it  supports  the  arrangement  of  visual  components  associated  to  an  arbitrary 
number  of  variables  and  interventions;  the  layout  of  the  components  will  be  automatically  updated 
according  to  the  elements  specified  in  the  scenario  editor.  It  is  thus  completely  generic,  not  tied  to  a 
given  scenario.  The  platform  also  provides  software  hooks  that  allow  for  additional  user-defined 
features,  two  of  which  are  provided  as  examples.  The  appendices  of  this  report  contain  technical  details 
regarding  the  content  of  user  logs  and  methods  that  should  be  overridden  in  order  to  implement  a 
software  hook. 

The  last  sections  of  this  report  detail  how  to  develop  a  scenario  from  scratch.  For  the  purpose  of 
facilitating  scenario  building  and  avoiding  source  code  development  by  users  who  are  not  proficient  at 
it,  a  scenario  editor  was  developed.  This  editor  reads  a  configuration  file  that  defines  every  single 
possible  parameter  (i.e.  name,  type,  description)  in  different  parts  of  simulation  entities,  and  then  fills  a 
user  interface  with  the  parameter  values  found  in  a  scenario  file.  Parameters  can  then  be  modified, 
variables  and  action  points  created  /  removed,  making  it  possible  for  users  to  build  a  scenario  that  will 
be  written  directly  to  a  CODEM  scenario  file  (0cdm0 extension),  and  loaded  by  a  simulator  thereafter. 
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Sommaire 


La  plateforme  exp0rimentale  d0velopp0e  dans  le  cadre  de  ce  projet  permettra  0  un  exp0rimentateur 
dSEtudier  comment  les  humains  en  arrivent  0  comprendre  des  syst0mes  /  situations  complexes.  Les 
participants  doivent  computer  des  mandats  impliquant  un  ou  plusieurs  participants  qui  ont  0  prendre 
des  d0cisions  sur  des  interventions  possibles  afin  dEkmener  la  situation  complexe  vers  un  0tat  d0sir0. 
Afin  de  supporter  les  exp0rimentateurs  dans  leurs  recherches  sur  la  prise  de  d0cision  en  situation 
complexe,  une  interface  utilisateur  des  plus  flexibles  a  0t0  d0velopp0e.  El  le  permet  aux  participants  de 
percevoir  ISEtat  courant  de  la  situation,  d0nspecter  le  diagramme  dSnfluence  d0crivant  les  relations  de 
cause  0  effet  connues  dans  un  syst0me,  de  pr0dire  ISEtat  de  la  situation  au  tour  suivant,  de  prendre  des 
d0cisions  en  allouant  des  points  dUctions  sur  diff0rentes  interventions,  de  lire  des  informations 
pertinentes  sur  ISEtat  de  la  situation,  ou  de  prendre  des  notes  sur  la  strat0gie  adopt0e.  En  plus  des 
fonctionnalit0s  pr0c0dentes,  interface  fournit  du  feedback  0  la  fin  de  chaque  tour  compl0t0  tout  en 
g0rant  ad0quatement  la  collaboration  /  comp0tition  entre  plusieurs  participants.  Le  pr0sent  document 
est  un  guide  de  IHUti lisateur  complet  sur  comment  utiliser  la  plateforme  de  mani0re  efficace. 

Ce  rapport  introduit  tout  dG&bord  interface  utilisateur  associ0e  0  la  plateforme  exp0rimentale.  Cette 
interface  a  0t0  con0ue  dime  mani0re  telle  quEfelle  supporte  le  r0arrangement  automatique  de  ses 
composantes  graphiques  en  fonction  du  nombre  de  variables  ou  interventions  pr0sentes  dans  le 
syst0me.  La  plateforme  d0finit  0galement  des  interfaces  logiciel les  qu0l  est  possible  dHmplanter  afin 
dajouter  des  fonctionnalit0s  pour  un  sc0nario  donn0.  Deux  exemples  de  telles  fonctionnalit0s  sont 
fournis  dans  ce  rapport.  Finalement,  les  annexes  fournissent  des  d0tails  suppl0mentaires  sur  le  contenu 
des  fichiers  de  log  ainsi  que  sur  les  m0thodes  qui  doivent  0tre  implant0es  afin  de  bien  utiliser  les 
extensions  logicielles. 

Les  derni0res  sections  de  ce  rapport  d0taillent  un  0diteur  graphique  qui  permet  la  cr0ation  de  sc0narios 
de  mani0re  g0n0rique  tout  en  assurant  la  validit0  du  contenu  ajout0  par  un  utilisateur.  En  lisant  un 
fichier  de  configuration,  cet  0diteur  conna't  tous  les  param0tres  que  peut  contenir  un  mod0le,  et  les 
rend  disponibles  0  IHLitilisateur.  Ce  dernier  peut  done  modifier  les  param0tres  0  sa  guise  et  sauvegarder 
le  r0sultat  de  son  travail  dans  un  fichier  de  sc0nario  CODEM  (extension  0  edm  0)  qui  peut  0tre  charg0 
directement  dans  un  simulateur.  Le  d0veloppement  dim  sc0nario  complet  en  est  ainsi  facilit0. 
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Introduction 


The  complex  decision  making  experimental  platform,  CODEM,  is  a  generic  and  flexible  test  bed  that  is 
intended  to  be  a  shareable  research  tool  to  stimulate  coordinated  and  synergetic  research  on  complex 
dynamic  problem  solving.  One  of  the  formal  requirements  about  the  current  experimental  platform  is 
that  a  typical  scenario  should  run  without  the  need  for  the  user  (either  an  experimenter  or  a  participant) 
to  write  a  single  line  of  source  code.  Due  to  this  requirement,  the  experimental  platform  is  constrained 
to  allow  the  development  of  a  specific  class  of  models  called  system  dynamics  models  (Sterman,  2000), 
which  define  a  situation  using  numerical  variables  and  where  influences  between  variables  are  positive 
or  negative  numerical  effects.  Additional  details  will  be  provided  in  the  following  sections. 

The  current  experimental  platform  involves  one  or  more  human  participants  that  have  to  make 
decisions  on  possible  interventions  in  order  to  steer  the  system  (or  situation)  to  a  desired  state.  For  that 
purpose,  a  highly  configurable  and  generic  user  interface  framework  was  built.  It  allows  for  a  participant 
to  perceive  the  current  situation,  inspect  influence  diagrams  describing  the  known  cause-effect 
relationships  in  the  system,  make  predictions  about  what  the  situation  will  look  like  in  the  next  turn, 
make  decisions  by  distributing  action  points  on  interventions,  reading  information  snippets  and  taking 
notes  on  what  the  current  strategy  is.  In  addition  to  the  latter  content,  the  user  interface  framework 
provides  useful  feedback  at  the  end  of  a  turn  and  at  the  end  of  a  mandate  while  adequately  displaying 
the  current  state  of  a  turn.  Several  participants  at  a  time  can  contribute  to  the  evolution  of  a  simulated 
situation,  either  working  collaboratively  or  competitively.  The  present  document  constitutes  a  complete 
user  guide  on  how  to  use  the  platform  effectively.  A  quick  start  reference  guide  is  provided  in  Appendix 
D. 

A  scenario  editor  was  built  in  order  to  facilitate  the  development  of  a  specific  scenario,  reading  and 
writing  directly  CDM  scenario  files.  In  order  to  avoid  the  need  of  writing  Java  source  code,  a  generic 
software  architecture  was  put  in  place,  which  allows  for  arbitrary  number  of  participants,  variables  and 
interventions  to  be  defined. 
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2  User  Guide  of  the  Experimental 
Platform 


The  main  goal  of  CODEM  is  to  study  how  humans  deal  with  complex  situations.  The  simulated  scenarios 
take  the  form  of  a  turn-based  strategy  game,  similar  to  previous  work  on  complex  problem  solving 
(D0rner,  1996).  Therefore,  a  user  interface  controlling  the  progress  of  a  game  was  built  and  integrated 
to  the  platform.  It  has  the  following  objectives: 

Provide  the  user  with  a  view  of  the  current  situation; 

Show  to  the  user  the  relations  between  the  variables  describing  the  situation; 

Allow  the  user  to  make  predictions  about  the  state  of  the  situation  in  the  next  turn; 

Allow  the  user  to  influence  the  current  situation  by  making  decisions  that  consist  of  allocating 
action  points  on  various  interventions; 

Allow  the  user  to  retrieve  information  about  the  situation  and  the  decisions  history; 

Allow  the  user  to  take  notes  during  his  mandate; 

Provide  the  user  with  a  feedback  on  variables  changes  that  occurred  during  a  turn  and  on  the 
provenance  of  these  changes,  as  well  as  his  prediction  error. 

The  experimental  platforms  user  interface  was  built  in  such  a  way  that  it  supports  the  arrangement  of 
visual  components  associated  to  an  arbitrary  number  of  variables  and  interventions;  the  layout  of  the 
components  will  be  automatically  updated  according  to  the  elements  specified  in  the  scenario  editor. 
Most  of  the  features  can  also  be  enabled  and/or  disabled  via  configuration  parameters  available  in  the 
scenario  editor  (see  Section  3.1  for  complete  details). 

Prior  to  starting  CODEM,  it  is  recommended  to  register  file  extensions  0.cdm0to  the  CODEM  executable, 
which  will  allow  starting  the  platform  via  a  double-click  on  a  valid  scenario  file  (0.cdm0  extension).  In 
order  to  do  so,  simply  open  the  scenario  editor  via  0CODEM_ScenarioEditor.bat0  and  choose  in  the 
menu  bar  0Config  /  Register  CDM  files0.  If  the  registration  succeeds,  at  computer  restart,  0.cdm0  files 
will  be  associated  to  a  new  icon  that  is  the  CODEM  logo.  Double-clicking  on  such  a  file  will  launch 
CODEM.  Note  that  scenario  files  are  stored  in  the  0data0  directory.  Just  after  CODEM  is  started  and 
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when  the  Identify  User0  parameter  is  set,  the  platform  asks  to  identify  the  participant,  session  and 
group  IDs.  Those  IDs  are  included  in  the  name  of  the  log  files,  located  in  the  ElogEI  directory. 

In  the  main  user  interface,  five  different  views  are  available  via  a  tabbed  pane:  situation,  prediction, 
decision,  information  and  notes.  Features  of  the  experimental  platform  have  been  separated  in  five 
views  due  to  the  need  of  recording  in  a  log  file  how  much  time  users  spend  doing  specific  subtasks 
(situation  assessment,  inspection  of  mutual  influences,  note  taking,  etc.)  while  completing  their 
mandate. 

A  view  that  provides  users  with  feedback  at  the  end  of  a  turn  is  also  available.  It  will  show  to  the  user 
the  evolution  of  the  situation  during  the  last  turn  and  the  prediction  errors  he  made.  Finally,  a  view  that 
summarises  the  entire  mandate  history  can  be  provided  at  the  end  of  a  mandate. 

It  should  be  noted  that  several  indications  can  be  shown  to  the  user  during  the  mandate  regarding  the 
status  of  the  simulator.  For  example,  when  waiting  for  other  participants,  an  image  is  displayed  that 
informs  the  user  about  the  current  status  of  the  system;  at  the  end  of  a  mandate,  images  can  be 
displayed  in  order  to  inform  the  user  as  to  whether  he  succeeded  or  failed  in  completing  the  mandate.  A 
user  will  not  be  able  to  close  any  window  that  would  terminate  the  simulation  without  reaching  the  end 
of  a  mandate.  There  is  only  one  way  to  terminate  a  mandate  prematurely:  pressing  the  CTRL+ALT+X 
keys  simultaneously.  Doing  so  is  equivalent  to  letting  the  situation  evolve  without  allocating  any  action 
point  to  interventions. 

In  order  to  fully  customize  the  user  interface  of  the  experimental  platform,  the  placement  of  the 
variables0labels  can  be  changed  by  the  user.  Hitting  the  0CTRL+E0  key  switches  from  0normal0  mode  to 
0editing0  mode.  In  editing  mode,  variables0labels  can  be  moved  around  the  user  interface  by  dragging 
them  with  the  mouse.  The  main  dialog  can  also  be  resized;  for  that  purpose,  simply  move  the  mouse 
cursor  to  the  edge  of  the  dialog.  A  0resize0  cursor  will  appear.  Then  press  the  left  mouse  button  and 
drag  the  edge  of  the  dialog  to  the  desired  size.  Hitting  0CTRL+E0  will  save  the  new  layout  and  size  to  a 
file  (default  is  0config/layout.xml0,  but  it  can  also  be  configured  in  the  editor),  which  will  be  reloaded 
next  time  the  experimental  platform  is  executed. 

The  following  sections  present  in  detail  how  the  interface  should  be  used.  The  reference  scenario  is  the 
prototype  of  a  complex  counterinsurgency  situation  developed  at  DRDC  Valcartier  that  includes  nine 
variables  and  in  which  the  user  can  affect  the  situation  via  seven  interventions. 

2.1  Situation  Tab 

The  Situation  Tab  (see  Figure  1)  displays  the  status  of  all  variables  that  are  involved  in  a  situation.  In 
order  to  win  the  game  in  the  context  of  the  counterinsurgency  scenario,  the  value  of  all  variables  must 
be  outside  of  the  red  region  displayed  on  coloured  indicators.  The  current  variables  value  is  indicated 
graphically  using  a  horizontal  black  line  while  the  previous  turns  value  is  shown  using  a  gray  line.  As 
turns  pass,  the  user  can  go  back  in  time  in  order  to  examine  the  values  of  previous  turns  using  the  slider 
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positioned  at  the  bottom  of  the  tab.  When  the  situation  tab  does  not  display  the  current  turn,  it  is 
greyed  out  in  order  to  indicate  that  it  does  not  show  values  associated  to  the  latest  turn.  Depending  on 
the  game  configuration  parameters,  the  user  is  asked  to  make  his  predictions  on  the  next  variables0 
values,  or  to  make  decisions  on  interventions,  or  both,  before  he  can  continue  to  the  next  turn  by 
pressing  the  button  located  in  the  tab  corresponding  to  the  last  operation  (decision  or  prediction).  This 
latter  button  is  only  enabled  when  mandatory  predictions  and/or  decisions  have  been  made.  It  should 
be  noted  that  when  the  platform  is  configured  with  a  time-limit  for  each  turn,  the  turn  advances 
automatically  when  the  time  limit  is  reached,  even  though  predictions  and  decisions  have  not  entirely 
been  completed. 
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Figure  1  -  Situation  Tab 


2.2  Relations  Tab 

The  Relations  Tab  (see  Figure  2)  provides  a  view  of  mutual  influences  on  variables  and  allows  for  a  user 
to  visualize  the  detailed  relations.  Each  arrow  drawn  in  the  tab  represents  an  actual  mutual  influence 
from  one  variable  to  another.  The  0|  |0  symbol  on  a  line  indicates  that  the  influence  will  be  applied  on 
the  variable  after  a  certain  delay  has  passed  (number  of  turns).  In  this  tab,  the  user  can  show  or  hide  the 
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outgoing  relations  of  one  variable  using  the  checkboxes  located  on  the  right  side  of  the  tab.  Moving  the 
mouse  cursor  over  a  variables  name  grays  out  relations  that  are  not  outgoing  of  the  selected  variable, 
i.e.  those  that  are  not  direct  influences.  Similarly,  moving  the  mouse  cursor  with  the  right  button 
pressed  over  a  variables  name  grays  out  relations  that  are  not  incoming  to  the  selected  variable,  i.e. 
those  that  do  not  have  a  direct  influence.  In  order  to  examine  a  relation  between  two  variables,  the  user 
must  click  on  the  relation  arrow.  If  details  of  a  mutual  influence  are  not  hidden,  a  chart  will  appear 
showing  the  associated  relation  (see  Figure  3). 


Figure  2  -  Relation  Tab 


On  the  chart,  a  red  dot  indicates  the  current  variables  value  and  its  associated  influence  on  the 
specified  variable.  The  delay  before  the  influence  takes  effect  is  displayed  below  the  chart  when  one  is 
specified.  A  0Details0  button  is  available  when  the  mutual  influence  (or  conditional  mutual  influence) 
owns  a  0Description0  parameter.  In  case  of  conditional  mutual  influences,  condition  instances  are 
evaluated  at  the  beginning  of  each  turn,  and  condition  labels  are  updated  according  to  the  result  of  this 
evaluation  (see  the  bottom  of  Figure  3).  The  values  of  the  influence  relation  are  updated  according  to 
the  users  selection  in  the  0Condition0  dropdown  menu.  The  current  active  condition  is  highlighted  in 
green. 
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Figure  3  -  Chart  of  Influence 


2.3  Prediction  Tab 

For  research  and  cognitive  testing  purposes,  it  can  be  very  useful  to  elicit  participantsElexpectations  on 
how  the  situation  will  evolve  in  the  next  time-step.  CODEM  even  makes  it  possible  to  create  a  prediction 
task  with  no  interventions  required.  The  Prediction  Tab  (see  Figure  4)  allows  the  user  to  make  his 
predictions  on  the  values  of  each  variable  for  the  next  turn.  Along  with  his  predictions,  the  user  can 
indicate  the  level  of  confidence  he  has  in  the  predictions.  When  the  prediction  confidence  parameter  is 
set  to  0Global,0  only  one  confidence  level  has  to  be  entered,  which  is  located  right  above  the  G3Done  / 
Next  TurnEI  button.  The  current  (C)  value  of  a  variable  and  the  predicted  (P)  value  text  fields  use  the 
same  color  code  as  the  coloured  indicators  displayed  in  the  situation  tab.  The  prediction  tab  may  not  be 
present  depending  on  the  game  configuration  parameters.  If  present,  the  user  must  complete  his 
predictions  before  he  can  pass  to  the  next  turn.  Likewise,  when  decisions  must  be  made  before 
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predictions,  the  prediction  tab  will  not  be  enabled  until  decisions  have  been  made.  Clicking  on  the 
ElDoneE  (or  EINext  TurnEI  depending  on  the  active  mode)  button  commits  predictions  entered  during  the 
current  turn  and  disables  any  further  changes  to  predictions  and  confidence  entries. 


Figure  4  -  Prediction  Tab 


2.4  Decision  Tab 

The  Decision  Tab  (see  Figure  5)  allows  the  user  to  intervene  in  the  situation  using  the  available  action 
points  of  a  given  turn  to  apply  interventions.  In  order  to  decide  how  many  points  to  spend  on  each 
intervention  type,  the  user  can  explore  effects  of  his  intervention  on  different  variables  using  the 
@Show@  buttons.  Another  element  to  take  into  account  is  that  some  variables  in  the  situation  provide  a 
number  of  action  points  for  the  next  turn.  The  number  of  action  points  available  depends  on  the 
variablesEK/alue. 

When  several  participants  are  collaboratively  working  on  a  mandate  (same  E5ide0  parameter),  they  can 
share  action  points  with  other  participants  of  the  same  side.  The  participant  to  which  action  points 
should  be  sent  is  selected  via  a  drop  down  menu,  and  the  number  of  action  points  is  adjusted  with  the 
up  and  down  buttons.  Clicking  on  the  E5end0  button  sends  the  correct  amount  of  action  points  to  the 
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selected  participant.  The  total  number  of  action  points  available  and  action  points  left  are  updated 
according  to  the  points  sent  /  received. 

At  every  point  in  time,  the  user  can  refer  to  the  decisions  he  made  in  the  previous  turns  using  the  slider 
available  at  the  bottom  of  the  tab.  When  he  is  ready,  the  user  spends  some  or  all  of  his  action  points 
using  the  green  arrows.  He  can  modify  his  decisions  until  he  presses  the  0Done0  (or  0Next  Turn0 
depending  on  the  active  mode)  button.  A  fraction  of  the  action  points  that  are  unspent  in  a  turn  will  be 
available  in  the  next  turn,  which  is  configured  via  the  HJnusedAPTransfer.0 


Situation  \  Relations  \  Prediction  \  Decision  \  Info  r  Notes 
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Figure  5  -  Decision  Tab 


2.5  Info  Tab 

The  Info  Tab  shows  game  history  information  in  four  sub-tabs.  The  first  one,  named  0Messages0  (see 
Figure  6)  displays  messages  that  are  added  using  information  text  in  the  default  category.  When  an 
information  text  is  specified  in  another  category,  a  corresponding  tab  is  created.  It  should  be  noted  that 
information  text  that  was  added  in  the  current  turn  is  displayed  in  black,  whereas  text  added  in  previous 
turns  are  displayed  in  light  gray  in  order  to  indicate  that  they  are  from  past  turns. 
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\  Situation  *  Relations  '  Decision  r  Info  '  Notes  ^  - — -  -^r  .  v'  , 

[  Messages  |  Diagram  j  History  |  Feedbacks  j 

Turn  #1 :  You  are  coordinating  a  multinational  effort  to  stabilize  a  failing  state  in  the  grips  of  a  rising  insurgency. 

Your  mission  is  to  return  the  host  nation  to  a  stable  and  self-sustaining  condition. 

The  operation  will  be  considered  a  success  if  all  situation  indicators  (except  the  mediating  variable)  are  outside  the 
RED  zone 

Your  mission  has  failed  if  the  allegiance  of  the  local  population  falls  to  zero. 

Your  tour  of  command  will  last  up  to  ten  turns  -  although  the  campaign  will  not  necessarily  be  over. 

International  support  to  the  coalition  forces  (and  to  the  insurgents)  is  represented  by  action  points. 

At  the  start  of  each  turn,  you  can  allocate  action  points  to  influence  the  state  of  affairs. 

Half  of  unspent  action  points  carry  over  to  the  next  turn. 

This  task  is  extremely  challenging.  It  is  highly  advised  to  carefully  consider  the  known  cause-effect  relations  in 
the  system  and  try  to  develop  an  effective  long  term  strategy. 


Figure  6  -  Info  Tab  (Messages) 


The  second  sub-tab,  named  EIDiagramEl  (see  Figure  7),  displays  the  evolution  of  the  game  variables.  It  is 
possible  to  hide  some  of  them  using  the  checkboxes  under  the  chart  legend. 
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Figure  7  -  Info  Tab  (Diagram) 

The  sub-tab  G3History0  (see  Figure  8)  displays  in  the  same  view  the  value  of  all  variables  and  the  decisions 
made  during  each  turn  of  the  game.  The  slider  should  be  used  to  go  back  in  time. 


I 
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Figure  8  -  Info  Tab  (History) 


The  last  sub-tab,  named  EFeedbacks0  (see  Figure  9),  provides  history  information  of  end  of  turn 
feedback  screens  (more  details  about  those  screens  are  provided  in  Section  2.7).  The  slider  is  used  to  go 
back  in  time,  while  the  buttons  0Next0  and  0Back0  are  used  to  navigate  between  the  variable  values 
changes  and  the  prediction  error  information. 
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Figure  9  -  Info  Tab  (Feedbacks) 


2.6  Notes  Tab 

The  Notes  Tab  (see  Figure  10)  can  be  used  whenever  needed  by  the  user  in  order  to  take  notes.  If  the 
user  needs  to  organise  his  notes,  tabs  can  be  created  by  clicking  on  the  0+0  tab.  A  name  can  be  given  to 
a  new  tab  at  its  creation.  A  tab  can  be  destroyed  by  right-clicking  on  its  title.  Use  the  text  field  in  the 
lower  part  of  the  tab  in  order  to  write  a  note  and  the  0Commit0  button  in  order  to  commit  the  new  note 
to  the  notes  history.  The  wall-clock  time  at  which  a  note  was  committed  as  well  as  the  current  turn  is 
used  to  identify  the  moment  when  a  user  took  a  particular  note.  If  a  note  was  not  committed  at  the  end 
of  a  turn,  CODEM  will  automatically  commit  it. 
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Figure  10  -  Notes  Tab 


2.7  End  of  Turn  Feedback  Screen 

At  the  end  of  each  turn,  a  feedback  screen  can  be  displayed  (see  Figure  11)  in  order  to  help  the  user 
understand  which  variables  had  influence  on  others  and  what  have  been  the  effects  of  his  interventions. 
In  order  to  examine  this  information,  the  user  needs  to  move  the  mouse  cursor  over  the  desired 
variables.  The  actual  number  (preceded  of  Ek-0or  0-0)  specifies  the  absolute  change  for  a  given  variable 
during  the  last  turn.  Incoming  arrows  display  the  contribution  of  corresponding  variables.  When  the 
number  in  red  is  followed  by  0|  |n0,  it  means  that  the  effect  was  delayed  by  0n0  turns  before  being 
applied  on  the  variable  in  the  current  turn.  The  effect  of  interventions  is  found  on  the  right  of  the  end  of 
turn  summary  dialog.  It  displays  the  effect  of  every  intervention  on  the  variable  over  which  the  mouse 
cursor  is  placed.  Right  clicking  on  one  variable  displays  the  effect  that  this  variable  had  on  others  using 
the  same  representation. 
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Figure  11  -  Feedback  screen  (End  of  turn  Summary) 


When  the  prediction  tab  is  activated,  another  feedback  screen  (see  Figure  12)  is  available.  It  can  be 
shown  by  clicking  on  the  0Next0  button.  This  view  displays  the  new  variables  values  and  the  predictions 
made.  The  user  can  see  how  accurate  he  was  in  his  prediction  by  looking  at  the  difference  between  the 
two  values  indicated  in  red,  or  in  blue  when  the  prediction  was  accurate.  The  user  can  click  on  the 
0Back0  button  in  order  to  go  back  to  changes  provenance.  It  should  be  noted  that  when  predictions  are 
available,  the  0OK0  button  will  only  be  enabled  when  the  prediction  error  view  has  been  visited. 
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Figure  12  -  Feedback  Screen  (Prediction  Error) 


2.8  Setting  the  Platform  to  Support  Multiple 
Participants 

The  experimental  platform  supports  several  participants  that  are  making  decisions  in  a  shared  situation, 
either  collaboratively  or  competitively.  Indeed,  the  same  infrastructure  is  used  with  player-specific 
situation,  relations,  and  intervention  tabs  whether  participants  are  collaborating  or  competing.  The  first 
step  to  accomplish  in  order  to  include  multiple  participants  in  one  simulation  is  to  define  a  distinct 
action  point  structure  and  set  of  possible  interventions  for  each  player  (see  Section  0  describing  the 
editor).  Participants,  each  having  a  specific  role  to  play  in  the  situation,  are  identified  by  a  user  name 
and  the  host  machine  on  which  they  will  work  (IP  address1  or  hostname). 

In  order  to  be  able  to  spawn  user  interfaces  on  remote  machines,  it  is  very  important  to  start  one  and 
only  one  ElUser  Interface  Dispatch  StarterEl  server  on  each  remote  machine  before  starting  the  main 
simulation  application.  This  server  actually  spawns  a  user  interface  that  is  configured  for  the  appropriate 
participant,  and  afterwards  controls  the  entire  data  exchange  between  the  user  interface  and  the 

1  In  order  to  find  the  IP  address  of  a  computer,  run  HpconfigH  in  a  command  line  and  look  for  the  IP  address  of  the 
network  adapter  that  is  currently  connected 
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simulator.  It  should  be  noted  that  the  multi-participants  platform  uses  Java  Remote  Method  Invocation 
(RMI)  and  that  it  will  only  work  in  local  area  networks  unless  appropriate  network  ports  are  opened.  The 
default  port  number  is  020450;  otherwise,  it  can  be  configured  with  the  0dispatchStarter.port0  system 
property.  Note  that  when  a  port  other  than  the  default  one  is  configured,  the  same  system  property 
should  be  set  on  every  Java  virtual  machine.  Also  note  that  every  participant  should  have  access  to  the 
same  version  of  executable  files.  If  this  is  not  the  case,  exceptions  will  be  thrown  during  the  objects0 
marshalling  process.  For  a  step  by  step  procedure  on  how  to  start  CODEM  for  multiple  participants,  see 
Section  D.l. 

2.9  Log  Files 

One  of  the  main  objectives  in  using  the  experimental  platform  with  human  participants  is  to  analyse  the 
strategy  they  employ  in  their  task  to  understand  and  influence  a  complex  situation.  Although  the  users 
screen  is  typically  captured  in  video,  which  can  then  be  analysed  a  posteriori  in  order  to  evaluate  various 
metrics  (e.g.  the  total  time  spent  observing  specific  data,  the  number  of  times  a  given  action  is 
performed),  such  an  approach  can  be  very  time  consuming  and  prone  to  error.  In  order  to  support 
experimenters  in  analysing  a  participants  actions  during  a  session,  logs  are  recorded  to  files;  one  for 
each  participant  that  contains  several  metrics,  and  another  one  that  contains  variables  values  and  action 
points  allocated  during  a  mandate.  A  detailed  description  of  every  log  entry  can  be  found  in  Appendix  A. 

2.10  Language  Configuration 

An  experimenter  has  the  ability  to  configure  every  single  text  label  present  in  the  user  interface.  For  that 
purpose,  resource  bundles  (simple  text  files),  which  contain  text  labels  that  should  be  displayed  in  the 
user  interface,  have  to  be  created.  System  properties  have  to  be  set  in  order  for  the  platform  to 
consider  the  right  language  configuration.  By  default,  the  user  interface  is  displayed  in  English.  In  order 
to  use  a  specific  resource  bundle,  add  the  following  JVM  arguments: 

•  -Dlanguage=the_language 

•  -Dcountry=the_country  (optional) 

•  -Dvariant=the_variant  (optional) 

Or  specify  the  above  properties  in  the  file  0config/CODEM.properties0. 

The  file  containing  the  labels  can  be  modified  via  the  scenario  editor  by  choosing  in  the  menu  bar 
0Config  /  Edit  Labels0.  For  more  information  about  building  a  new  language  configuration  file,  follow  the 
steps  detailed  in  Appendix  B. 
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3  Scenario  Editor®  User  Guide 


A  scenario  editor  was  built  that  allows  configuring  various  features  of  the  experimental  platform  (e.g. 
visual  appearance,  enable/disable  features)  as  well  as  the  complex  dynamic  system  (e.g.  variables  and 
influences,  interventions).  This  editor  reads  a  configuration  file  that  defines  every  single  possible 
parameter  (i.e.  name,  type,  description)  in  different  parts  of  simulation  entities,  and  then  fills  a  user 
interface  with  the  parameter  values  found  in  a  CDM  scenario  file  that  is  opened  and  saved  using  the 
0File0  menu  from  the  menu  bar.  Parameters  can  then  be  modified,  variables  and  action  points  created  / 
removed,  making  it  possible  for  users  to  build  appropriate  data  structures  that  can  be  loaded  directly 
into  the  simulator  via  a  CDM  scenario  file. 

The  next  sections  present  an  exhaustive  list  of  parameters  that  one  can  set  for  every  data  structure  used 
to  configure  the  experimental  platform  via  the  scenario  editor.  A  screen  capture  from  the  scenario 
editor  shows  a  typical  configuration  of  parameters.  Parameters  that  are  displayed  in  those  screen 
captures  originate  from  a  counterinsurgency  /  stability  operations  scenario  that  was  developed  in  order 
to  demonstrate  the  capabilities  of  the  platform. 

As  a  general  guideline  for  every  parameter  contained  in  the  scenario  editor,  a  label  identifies  the 
parameters  name,  a  text  field  contains  the  parameters  value  and  a  checkbox,  when  checked,  enables 
the  actual  parameter.  When  available  (i.e.,  defined  in  the  scenario  editor  configuration  file),  a  tooltip  is 
shown  as  soon  as  the  user  positions  the  mouse  over  the  label  or  text  field,  which  provides  a  description 
of  the  parameter  (e.g.  valid  values,  general  instructions).  Similarly,  a  0?0  character  besides  the  title  of  a 
group  of  parameters  means  that  a  tooltip  will  be  shown  when  the  user  positions  the  mouse  over  the 
panel. 

In  order  to  provide  greater  flexibility  to  a  scenario,  it  is  possible  to  implement  various  conditions  and 
statements  using  Javascript  expressions;  conditions  should  return  a  Boolean  value,  whereas  other 
statements  will  manipulate  variables  or  return  integer  values.  Javascript  expressions  include  several 
attributes;  one  for  each  variable,  referenced  by  their  ID,  and  0iteration,0  which  is  the  current  turn  during 
a  mandate.  The  reference  in  an  expression  to  other  attributes  will  result  in  Javascript  errors.  However, 
most  common  logic  and  arithmetic  operators  can  be  used  straightforwardly. 
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3.1  Generic  Scenario  Parameters 


In  order  to  edit  a  scenario,  double-click  on  0CODEM_ScenarioEditor.bat0  and  open  a  CDM  file  via  the 
0File  /  Open0  menu.  A  scenario  firstly  contains  several  parameters  that  are  used  to  configure  the 
experimental  platforms  main  user  interface  appearance  as  well  as  features  that  will  be  enabled  in  it. 
Figure  13  shows  parameters  that  affect  the  main  dialog,  Figure  14  displays  parameters  that  determine 
conditions  for  the  termination  of  a  mandate,  Figure  15  shows  parameters  that  configure  features 
available  in  the  dialog,  and  Figure  16  shows  parameters  that  determine  the  behaviour  of  the  interface 
between  turns  and  when  the  mandate  is  over. 


Main  Dialog  Parameters 

Title  Stability  Operations  Game  |v] 

Background  Image  data/afghan.jpg  P71 

Background  Sound 

Click  Sound  data/dick.wav  |y] 

Identify  User  true  ~  ^  [v) 

Layout  File  config/layout.xml  g] 

Random  Seed  -1  P71 


Figure  13  -  Scenario  parameters  "Main  Dialog  Parameters"  group 


End  of  Game  Parameters 


Max  Turns  10 


WinningCondition  l_fbrces  >=  6  &&  criminality  >=  9 
WinningCondition .  custom 


LosingCondition  populafion_allegiance  ==  0 
LosingCondition .  custom 


m 

m 

□ 

m 

□ 


Figure  14  -  Scenario  parameters  "End  of  Game  Parameters"  group 
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Prediction  Mode 
End  of  turn  feedback  mode 
DedsionTab 
ActionPoints .  Details 
RelationsTab 
Relations .  EnableSho  wHide 
InfbTab 
InfbTab.  history 
InfoTab.  diagram 
InfoTab .  endOffurn 
NotesTab 
Prediction  Confidence 
HistoryEnabled 
TimeLimit.Dedsion 
TimeLimit.Turn 
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Figure  15  -  Scenario  parameters  "Game  Mode  Parameters"  group 


Transition  and  End  of  Mandate  Parameters 


EndDialogDelay 
T urnT ransitionDelay 
EndOfT urnFeedback 
EndOfMandateSummary 
TurnTransitionlmage 
TurnWaitlmage 
EndOfMandatelmage 
Winninglmage 
Losinglmage 


5000 


1000 


true 


false 


data  /wait, 


jpg 


data/TheEnd.jpg 


data/you-win.gif 


data/you-fai.jpg 
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Figure  16  -  Scenario  parameters  "Transition  and  End  of  Mandate  Parameters"  group 


Table  1  -  Detailed  parameters  of  a  scenario 


Name 

Type 

Valid  values 

Description 

Title 

String 

Any  String 

Title  shown  in  the  title  bar  of  the  main  user 
interface  of  the  experimental  platform 

Background  Image 

String 

Any  valid  image  file 

name 

File  name  and  path  relative  to  the  root 
directory  containing  an  image  that  will  be 
shown  behind  the  main  control  dialog  box 
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Background  Sound 

String 

Any  valid  sound  file 
(wav  or  mp3) 

File  name  and  path  relative  to  the  root 
directory  containing  a  sound  that  will  be 
played  in  loop  during  the  whole  mandate 

Click  Sound 

String 

Any  valid  sound  file 
(wav  or  mp3) 

File  name  and  path  relative  to  the  root 
directory  containing  a  sound  that  will  be 
played  every  time  the  user  clicks  the  mouse 

Identify  User 

Boolean 

True,  False 

True:  asks  for  participantID,  sessionID  and 
groupID  at  the  beginning  of  a  mandate;  False: 
does  not  ask  for  user  identification  (default). 
participantID,  sessionID  and  groupID  can  be 
set  via  system  properties  on  the  command 
line  (e.g.  0DparticipantlD=my id) 

Layout  File 

String 

Any  valid  XML  file 

name 

File  name  and  path  relative  to  the  root 
directory  that  contains  the  position  /  size  of 
the  different  variable  labels  part  of  the  main 
user  interface 

Random  Seed 

Integer 

-1,... 

A  seed  that  initializes  the  random  number 
generator;  -1:  uses  a  seed  that  depends  on 
time  (default);  other  integer:  fixed  seed 

Max  Turns 

Integer 

-1,... 

Maximum  number  of  turns  that  a  mandate 
can  last.  When  reached,  the  mandate 
terminates  in  neutral  state 

WinningCondition 

String 

Any  valid  Javascript 
expression  that 

evaluates  to  a 

Boolean 

Javascript  expression  that  will  be  evaluated 
after  each  turn.  When  true,  the  mandate 
terminates  in  winning  state.  Variables  should 
be  referred  to  with  their  ID.  Has  priority  over 
neutral  and  losing  state 

WinningCondition. 

custom 

String 

Any  valid  class  name 
that  implements 

Conditionl 

When  successfully  loaded,  an  instance  of  this 
class  will  be  evaluated  after  each  turn.  The 
mandate  terminates  in  winning  state  when  it 
returns  true.  Has  priority  over  neutral  and 
losing  state 

LosingCondition 

String 

Any  valid  Javascript 
expression  that 

evaluates  to  a 

Boolean 

Javascript  expression  that  will  be  evaluated 
after  each  turn.  When  true,  the  mandate 
terminates  in  losing  state.  Variables  should  be 
referred  to  with  their  ID.  Has  priority  over 
neutral  state 

LosingCondition. 

custom 

String 

Any  valid  class  name 
that  implements 

Conditionl 

When  successfully  loaded,  an  instance  of  this 
class  will  be  evaluated  after  each  turn.  The 
mandate  terminates  in  losing  state  when  it 
returns  true.  Has  priority  over  neutral  state 

Prediction  Mode 

Integer 

0,  1,2 

0:  no  prediction  (default);  1:  prediction  first, 
then  decision;  2:  decision  first,  then  decision 

End  of  turn  feedback 

mode 

Integer 

0,1 

0:  feedback  showing  changes  and  provenance 
of  effects  (default);  1:  do  not  show 
provenance  of  changes.  Applies  for  both  end 
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of  turn  information  in  the  info  tab  and  the 
summary  at  the  end  of  a  turn 

DecisionTab 

Integer 

0,1 

0:  decision  tab  inactive  (default);  1:  decision 
tab  active 

ActionPoints.  Details 

String 

All,  Contribution, 

Available  or  None 

In  the  decision  tab  -  All:  shows  action  points 
contribution  and  action  points  available 
(default);  Contribution:  shows  only  action 
points  contribution;  Available:  shows  only 
action  points  available;  None:  does  not  show 
anything 

RelationsTab 

Integer 

0,... 

Compose  an  integer  with  activated  bits,  0: 
inactive  (default);  1:  active  +  full  features;  2: 
remove  chart  feature;  4:  remove  condition 
details  feature;  8:  remove  condition 
description  feature 

Relations. 

EnableShowHide 

Boolean 

True,  False 

True:  enables  checkboxes  for  showing  / 
hiding  relations  in  the  relations  tab  (default); 
False:  disables  checkboxes 

InfoTab 

Integer 

0,1 

0:  inactive,  1:  active  (default) 

InfoTab. summary 

Boolean 

True,  False 

True:  activate  summary  subtab  in  info  tab; 
False:  deactivate  summary  subtab  (default) 

InfoTab. history 

Boolean 

True,  False 

True:  activate  history  subtab  in  info  tab; 

False:  deactivate  history  subtab  (default) 

InfoTab. endOfTurn 

Boolean 

True,  False 

True:  activate  end  of  turn  subtab  in  info  tab; 
False:  deactivate  end  of  turn  subtab  (default) 

NotesTab 

Integer 

0,1 

0:  inactive,  1:  active  (default) 

Prediction 

Confidence 

String 

Yes,  No,  Global 

Yes:  need  to  enter  a  confidence  value  in  the 
prediction  tab  for  every  variable;  No:  no  need 
to  enter  a  confidence  value  in  prediction  tab 
(default),  Global:  need  to  enter  a  global 
confidence  value  in  the  prediction  tab 

HistoryEnabled 

Boolean 

True,  False 

True:  enables  history  in  situation  and  decision 
tabs  (default);  False:  does  not  enable  history 

TimeLimit.  Decision 

Integer 

-1,... 

Number  in  seconds  that  imposes  a  time  limit 
for  making  a  decision.  Countdown  starts 
when  decision  tab  is  consulted  for  the  first 
time.  -1:  no  limit  (default) 

TimeLimit.Turn 

Integer 

-1,... 

Number  in  seconds  that  imposes  a  time  limit 
for  completing  a  turn.  Countdown  starts 
when  the  turn  begins.  -1:  no  limit  (default) 

EndDialogDelay 

Integer 

-1,... 

Amount  of  time  the  end  dialog  is  shown,  in 
milliseconds.  -1  shows  the  dialog  until  it  is 
closed  by  the  user  when  no 
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endOfMandateSummary.  Default:  5000 

TurnTransitionDelay 

Integer 

0,... 

Amount  of  time  the  turn  transition  dialog  is 
shown,  in  milliseconds.  Default:  3000 

EndOfTurnFeedback 

Boolean 

True,  False 

T rue:  end  of  turn  feedback  screen  is  shown; 
False:  no  feedback  screen  at  the  end  of  a  turn 
(default) 

EndOfMandate 

Summary 

Boolean 

True,  False 

True:  end  of  mandate  summary  screen  is 
shown;  False:  no  screen  is  shown  (default) 

T  urnT  ransitionl  mage 

String 

Any  valid  image 

name 

file 

File  name  and  path  relative  to  the  root 
directory  containing  an  image  that  will  be 
shown  between  the  turns 
0turnTransitionDelay0ms. 

TurnWaitlmage 

String 

Any  valid  image 

name 

file 

File  name  and  path  relative  to  the  root 
directory  containing  an  image  that  will  be 
shown  when  waiting  for  other  participants  to 
complete  their  turn 

EndOfMandate 

Image 

String 

Any  valid  image 

name 

file 

File  name  and  path  relative  to  the  root 
directory  containing  an  image  that  will  be 
shown  when  a  mandate  is  over  without 
winning  nor  losing  0endDialogDelay0  ms. 

Winninglmage 

String 

Any  valid  image 

name 

file 

File  name  and  path  relative  to  the  root 
directory  containing  an  image  that  will  be 
shown  when  a  mandate  is  over  in  winning 
state  0endDialogDelay0  ms. 

Losinglmage 

String 

Any  valid  image 

name 

file 

File  name  and  path  relative  to  the  root 
directory  containing  an  image  that  will  be 
shown  when  a  mandate  is  over  in  losing  state 
0endDialogDelay0  ms. 

Figure  17  shows  controls  that  allow  one  to  define  which  variables  and  action  points  will  be  instantiated 
in  a  given  scenario.  On  the  left,  variables  and  action  points  that  are  available  but  not  activated  for  that 
scenario  can  be  found.  Selecting  such  an  item  and  clicking  the  0Add  >0  button  declares  an  instance  of 
that  type.  The  ID  of  a  variable  or  action  point  is  set  at  the  time  of  their  creation  in  the  associated  tabs. 
Note  that  IDs  should  not  contain  any  special  character  such  as  spaces.  The  0Label0  parameter  allows 
specifying  how  variables  and  action  points  will  appear  in  the  user  interface  without  any  restriction.  In 
order  to  remove  an  agent  instance  from  a  simulation,  a  user  should  select  it  in  the  right  column  and  click 
the  0<  Rem. 0  button. 
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Variables  (?) 


Add  > 


<  Rem. 


criminality 

cultural_understanding 

host_nation_governance 

infrastructures 

insurgent_forces 

local_forces 

local_media 

population_allegiance 

sodo_economic_welfare 

x_dist_criminality 

x_dist_governance 

x  dist  infrastructures 


Acton  Points  (?) 


BlueForcePl 

BlueForceP2 


Figure  17  -  Scenario  parameters  "Instances"  group 

3.2  Description  of  Variables 


A  set  of  variables  and  their  mutual  influences  define  a  complex  situation  that  is  updated  after  every 
turn.  The  properties  of  variables  should  be  defined  with  the  scenario  editor.  Figure  18  shows  controls 
that  are  used  to  select,  add  and  remove  variables  from  the  set  of  defined  variables.  Clicking  the  0Add0 
button  asks  the  user  to  name  a  variable.  Removing  a  variable  deletes  the  corresponding  data  structure. 
Selecting  a  variable  updates  the  value  and  enabled  state  of  every  single  parameter  associated  to  that 
variable.  It  is  possible  to  duplicate  the  data  structure  associated  to  a  variable  via  the  0Duplicate0  button. 
The  user  is  then  asked  to  name  the  new  variable. 


Variables  host_nation_governance 


»■  Add  Remove  Duplicate 


Figure  18  -  Variable  addition  and  removal  controls 


Simple  parameters  are  associated  to  every  variable  (Figure  19).  Those  include  minimum  and  maximum 
values,  the  configuration  of  target  values  and  the  initial  value  of  a  variable.  In  particular,  parameters 
that  specify  the  range  of  values  associated  to  Ejgreen,@  0orange,0  and  0red0  categories  are  found  in 
simple  parameters  (Figure  20).  More  details  on  all  the  parameters  can  be  found  in  Table  2. 
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Parameters 

InitialValue  8  j  |y] 

MinValue  0  |  (y] 

MaxValue  20  [yj 

MinGreen  15  lyl 

MaxGreen  20  |y] 

MinOrange  6  |  |y] 

MaxOrange  14  |  |y] 

NoColor  |  [□ 

Uncertainty  IH 

Label  score  ]  |y] 

VisibleTo  [rl 

HideDetailsTo  ~|  [Pi 

IsMediating  True  [y] 

IsAgent  ~|  (T1 

Order  4  liyl 

Description 


ComputedValue  host_nation_governance  +  culturaljjnderstanding  [y] 


Figure  19  -  Simple  variables  parameters 


20  20 


minGreen 


minOrange 


0  0 


maxOrange 


maxGreen 


Figure  20  -  Details  of  the  color  categories  for  variables  values 


Table  2  -  Details  of  simple  variables  parameters 


Name 

Type 

Valid  values 

Description 

InitialValue 

Integer 

MinValue, 

MaxValue 

Value  that  should  be  found  within  the  range 
MinValue  and  MaxValue  that  is  the  initial  value  of 

that  variable 

MinValue 

Integer 

Any  integer  lower 
than  MaxValue 

The  minimum  value  of  that  variable 

MaxValue 

Integer 

Any  integer  larger 
than  MinValue 

The  maximum  value  of  that  variable 
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MinGreen 

Integer 

MinValue, 

MaxValue 

The  minimum  value  that  defines  the  green  range 

MaxGreen 

Integer 

MinGreen, 

MaxValue 

The  maximum  value  that  defines  the  green  range 

MinOra  nge 

Integer 

MinValue, 

MaxValue 

The  minimum  value  that  defines  the  orange  range 

MaxOrange 

Integer 

MinOrange, 

MaxValue 

The  maximum  value  that  defines  the  orange  range 

NoColor 

Boolean 

True,  False 

True:  remove  green,  orange  and  red  ranges  from 
variables  representations  and  fills  the  range  with  a 
blue  color;  False:  fills  the  range  with  specified 
green,  orange  and  red  colors  (default) 

Uncertainty 

Integer 

0,... 

When  not  0,  the  real  value  of  a  variable  is  found 
inside  a  +/-  uncertainty  range  around  the 
displayed  value.  Only  affects  values  displayed  in 
the  interface,  not  in  the  simulation.  Default:  0 

Label 

String 

Any  valid  String 

The  label  that  identifies  a  variable  in  the  user 

interface 

VisibleTo 

List<String>2 

Any  valid  list  of 

[all]:  visible  to  all  users  (default);  [none]:  visible  to 

Strings 

nobody;  [userl,  user2]:  list  of  participants  for 
which  this  variable  will  be  visible  in  the  interface 

HideDetailsTo 

List<String> 

Any  valid  list  of 

[none]:  hide  details  to  nobody  (default);  [all]:  hide 

Strings 

details  to  all  users;  [userl,  user2]:  list  of 
participants  for  which  details  of  this  variable  will 
be  hidden  (value  not  available)  in  the  interface 

IsMediating 

Boolean 

True,  False 

True:  when  a  variable  is  considered  as  a  mediating 
variable,  representing  it  differently  in  the  situation 
tab,  and  removing  it  from  prediction  tab;  False: 
variable  is  not  mediating  (default) 

IsAgent 

Boolean 

True,  False 

True:  when  a  variable  is  considered  as  an  GJagentE] 
variable,  representing  it  differently  in  the  situation 
tab;  False:  variable  is  not  0agent@ (default) 

Order 

Integer 

Any  integer 

The  number  of  appearance  of  that  variable  when 
predefined  layout  is  unavailable.  Smaller  values 
are  sorted  first 

Description 

String 

Any  valid  String 

A  description  of  the  variable  that  is  shown  as  a 
tooltip  of  variable  labels  in  situation,  relation  and 
prediction  tabs3 

Computed 

String 

Any  valid  Javascript 

An  expression  that  overrides  the  value  set  by 

Value 

expression  that 

mutual  influences.  It  is  evaluated  at  the  beginning 

evaluates  to  an 

of  a  turn  and  takes  into  account  the  values  of  the 

2  A  general  guideline  for  lists  is  to  put  elements  around  bracket  characters  (Gpand  E|G),  separated  by  a  comma  (GJG) 

3  For  descriptions  that  are  longer  than  one  line  of  text,  new  lines  can  be  created  by  using  the  HTML  notation.  For 
that  purpose,  begin  the  description  with  0<html>H,  create  a  new  line  by  inserting  0<p/>l2]  and  end  your  description 
using  E3</html>H  (e.g.  <html>First  line  <p/>  Second  line  </html>).  The  same  comment  applies  to  every  field  that 
acts  as  a  description  object  in  EN/ariablesHand  HAction  PointsH 
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Integer  previous  turn.  Computed  values  are  processed  in 

the  order  set  by  the  0Order0  parameter 


3.2.1  Mutual  Influences 


Variables  influence  each  other  via  mutual  influence  relations.  A  mutual  influence  is  a  relation  that 
associates  a  relative  change  applied  to  a  variable  and  the  current  value  of  a  variable.  As  an  example, 
Figure  21  shows  influence  values.  For  instance,  when  the  domain  value  is  010,111  the  influence  is  00.0 
However,  when  the  domain  value  is  018,0  the  influence  is  02.0  The  experimenter  can  configure  the 
opacity  (how  much  details  are  shown)  of  a  mutual  influence  in  the  main  user  interface  in  several  ways. 
Firstly,  it  is  possible  to  hide  completely  a  relation  from  the  user.  Therefore,  the  user  will  not  be  aware 
that  a  relation  between  two  variables  exists.  Secondly,  it  is  possible  to  disable  revealing  details  of  the 
actual  relation  to  a  user.  Therefore,  the  user  is  aware  of  the  presence  of  a  relation  but  cannot  access  the 
actual  influence  values.  Thirdly,  it  is  possible  to  display  0dummy0  relations  that  replace  0real0  relations. 
Therefore,  the  user  is  aware  of  a  relation  that  can  exist  or  not  in  the  simulation.  It  is  the  experimenters 
role  to  specify  the  configuration  of  each  relation,  and  to  notify  the  participant  accordingly  via  the 
0description0  parameter  or  information  texts. 


Figure  21  -  Sample  chart  for  the  influence  editor 
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In  order  to  set  mutual  influences  with  the  scenario  editor,  one  should  look  into  the  0Variables0tab  in  the 
Elnfluences0  section  (Figure  22).  Clicking  on  the  0Add0  button  will  ask  the  user  to  specify  the  variable  for 
which  the  mutual  influence  should  be  created.  The  actual  variable  should  be  selected  from  a  combo  box 
that  contains  every  instantiated  variable  (Figure  17).  Clicking  the  0Remove0  button  will  delete  the 
selected  mutual  influence.  Clicking  the  0Change0  button  asks  the  user  to  choose  a  replacement  variable 
for  the  currently  selected  influence.  More  details  on  every  parameter  can  be  found  in  Table  3.  Note  that 
clicking  on  the  0Edit0  button  associated  to  the  0Values0  parameter  will  display  a  chart  similar  to  the  one 
shown  in  Figure  21  in  which  values  can  be  edited  by  the  user.  It  is  thus  easier  for  a  user  to  specify  a 
relation  by  dragging  the  cursor  on  a  chart  rather  than  modifying  values  by  hand.  The  0Set0  button  is 
used  to  set  the  number  of  values  present  in  the  domain,  while  clicking  0Cancel0  cancels  any  change, 
0Reset0  resets  values  to  the  state  they  were  when  the  dialog  was  opened  and  0OK0  commits  values  to 
the  scenario  editors  text  field. 


Influences 


jnsurgent forces 

j  t  Add 

Remove  II  Change 

Delay 


□ 


Values  j  2,  -1,  -1,  -1,  -1,  -1,  -1,  -1,  -1,  -1,  -1, 0,  0,  0,  0,  0]  |  Edit  |  g] 
Noise  □ 

Hidelnfluence 

HideDetails  |  IH 

Dummy 

Description  Enforcing.  The  worse  the  crime  rate,  the  more  it  generates  criminality  fv] 


Figure  22  -  Variables'  mutual  influences  parameters 


Table  3  -  Details  of  "Influences"  parameters 


Name 

Type 

Valid  values 

Description 

Delay 

Integer 

0,... 

A  delay  introduced  in  the  application  of  the  mutual 
influence.  Shown  in  the  chart  dialog 

Values 

List<lnteger> 

Any  list 

integers 

of  The  actual  influence  on  the  specified  variable  for 
each  value  that  the  current  variable  can  take.  The 
size  of  the  list  should  be  EfnaxValue-minValue+10, 
except  for  0dummy0  relations  that  can  be  of  any 
size 

Noise 

Integer 

0,... 

Random  noise  added  to  the  influence  value. 

Default:  0 

Hidelnfluence 

Boolean 

True,  False 

True:  hides  the  relation  from  the  user  interface; 
False:  shows  the  relation  in  the  user  interface 
(default) 

HideDetails 

Boolean 

True,  False 

True:  disables  clicking  the  relation  in  the  user 
interface;  False:  enables  clicking  the  relation  in  the 
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user  interface  (default) 

Dummy 

Boolean 

True,  False 

True:  displays  a  relation  in  the  user  interface  but 
does  not  consider  it  in  the  simulation;  False:  the 
relation  is  considered  in  the  simulation  (default). 
Dummy  has  priority  over  0real0  relations  for  being 
displayed  in  the  user  interface 

Description 

String 

Any  valid  String 

A  description  of  the  current  relation  that  will  be 
available  in  the  chart  dialog  with  the  0Details0 
button 

3.2.2  Conditional  Mutual  Influences 


In  order  for  the  mutual  influence  of  a  variable  to  change  according  to  the  situations  state,  it  is  possible 
to  specify  Biconditional  Influences!?]  (Figure  23).  For  that  purpose,  a  default  relation  can  be  specified 
(BDefault  Relations  section)  as  well  as  one  or  several  condition  instances.  Clicking  the  0Add0  button  in 
condition  instances  will  create  a  new  data  structure  that  stores  condition  instances  and  will 
automatically  assign  an  ID  to  it.  The  latter  data  structure  contains  a  0Condition0  parameter  that  is  in  fact 
a  Javascript  statement4,  which  is  evaluated  to  either  0true0or  0false.0  Table  4  shows  a  summary  of  most 
frequently  used  Javascript  operators.  The  first  condition  instance  that  is  evaluated  to  true  will  be 
considered.  There  is  no  specific  order  specification,  so  the  scenario  designer  should  make  sure  that 
conditions  are  mutually  exclusive,  i.e.  that  only  one  is  evaluated  to  true  at  the  same  time.  When  all 
conditions  are  evaluated  to  false,  the  default  relation  is  used.  The  0Label0  parameter  is  used  to  replace 
the  condition  statement  when  a  user  requests  details  about  a  conditional  influence.  It  therefore 
simplifies  the  statement  that  identifies  a  condition,  but  is  optional.  By  default,  the  actual  condition  is 
displayed.  Excluding  the  0Condition0  and  0Label0  parameters,  the  others  have  the  same  signification  as 
those  contained  in  0lnfluences.0  Adding  and  removing  conditional  mutual  influences  uses  the  same 
principle  as  mutual  influences.  It  should  also  be  noted  that  conditional  mutual  influences  have 
precedence  over  mutual  influences,  which  means  that  when  conditional  and  normal  influences  affect  a 
given  variable,  the  conditional  influence  has  priority  when  calculations  are  performed  in  the  simulator. 


4  For  more  details  about  the  Javascript  syntax,  see  https://developer.mozilla.org/en/Rhino  documentation. 
External  Java  classes  are  limited  to  EJava.Iang.MathEl  Note  that  there  is  a  potential  security  breach  here  because 
arbitrary  code  can  be  executed  (http://codeutopia.net/blog/2009/01/02/sandboxing-rhino-in-iava/) 
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Conditional  Influences  (?) 
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Figure  23  -  Variables'  conditional  mutual  influences  parameters 


Table  4  -  Summary  of  Javascript  operators 


Operator 

Description 

== 

Equality  operator 

!= 

Inequality  operator 

II 

Boolean  0or0  operator 

&& 

Boolean  0and0 operator 

< 

Boolean  0smaller  thanHoperator 

<= 

Boolean  0smaller  than  or  equal0operator 

> 

Boolean  0larger  than0operator 

>= 

Boolean  0larger  than  or  equal0  operator 

+ 

Addition  operator 

- 

Subtraction  operator 

* 

Multiplication  operator 

/ 

Division  operator 

% 

Modulo  operator 

= 

Assignment  operator 

+= 

Combined  addition  and  assignment  operator 

.= 

Combined  subtraction  and  assignment  operator 
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*_ 

Combined  multiplication  and  assignment  operator 

/= 

Combined  division  and  assignment  operator 

if(cond.)  {code;}  else 

Conditional  statement  0  code  returns  a  value  (no  return  statement  needed) 

if{code;}  else  {code;} 

or  manipulates  variables 

3.3  Description  of  Action  Points 

Action  points  allow  a  user  to  have  an  effect  on  how  the  situation  will  evolve  in  time  via  interventions  on 
the  situation.  At  the  beginning  of  each  turn  of  a  mandate,  a  number  of  action  points  is  allocated  to  each 
participant.  This  number  typically  depends  on  preset  parameters  and  on  the  situations  state.  Action 
points  obey  to  the  same  principle  as  mutual  influences  except  that  the  influence  on  a  variable  is  not  a 
function  of  a  variables  value,  but  rather  a  function  of  the  number  of  action  points  that  are  allocated  on 
a  given  intervention.  A  fraction  of  the  action  points  that  are  not  allocated  during  a  turn  will  be  available 
in  the  following  turn,  which  can  be  configured  via  the  0UnusedAPTransfer0  parameter.  Adding  and 
removing  action  points  in  a  scenario  is  performed  using  controls  that  are  shown  in  Figure  24.  A  new  or 
duplicated  action  point  data  structure  has  to  be  named  with  a  unique  ID  for  future  reference.  More 
details  on  parameters  available  in  the  configuration  of  action  points  can  be  found  in  Table  5. 


Action  Points 


_ 

Duplicate 

Figure  24  SI  Action  points  addition  and  removal  controls 


Base  Parameters 
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Figure  25  -  Action  points  base  parameters 


Table  5  -  Details  of  parameters  associated  to  Action  Points 


Name 

Type 

Valid  values 

Description 

MinimumPoints 

Integer 

0,... 

The  minimal  number  of  action  points  available 
at  the  beginning  of  a  turn.  Contribution  of 
variables  and  unused  action  points  are  added 
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to  this  number  to  calculate  the  total  number 
of  available  action  points  in  a  given  turn 

StartingAction 

Points 

Integer 

-MinimumPoints, 

The  initial  number  of  additional  action  points. 
Replaces  variables  contribution  in  the  first 
turn 

UnusedAPTransfer 

Float 

0. 0-1.0 

Proportion  of  unused  action  points 
transferred  to  the  next  turn 

Host 

String 

Any  valid 

hostname  or  IP 

address 

The  host  on  which  the  specified  participant 
will  be  performing  his  work.  Use  0localhost0in 
order  to  spawn  the  main  user  interface  in  the 
simulators  process.  Note  that  only  one  user  is 
supported  per  computer 

User  Name 

String 

Any  valid  String 

A  name  identifying  the  user  that  will  be  part 
of  the  main  dialogs  title  and  the  users  log  file 

name 

Sides 

List<String> 

Any  valid  list  of 
Strings 

List  of  sides  that  this  participant  is  part  of. 
Participants  that  are  part  of  the  same  sides 
can  share  action  points.  Default:  []  (no  sides) 

Implementation 

String 

Any  valid  class 
name  that 

implements 
appropriate 
interfaces 

Specifies  the  class  that  implements  an  actual 
participant.  Local  and  remote  participants  are 
distinguished,  i.e.  local-only  participants 
should  implement  UIDispatchAdapterl  and 
remote  participants  should  implement 
UlRemoteDispatchAdapterl.  Default:  0default0 
uses  the  default  implementation  that  displays 
the  standard  user  interface 

3.3.1  Interventions 


Interventions  that  a  user  can  perform  on  the  situation  are  also  specified  in  the  EAction  Points0tab  of  the 
scenario  editor.  Parameters  include  the  minimum  and  maximum  values  as  well  as  the  relations  defining 
how  interventions  influence  variables  of  a  situation.  Figure  26  shows  the  details  of  the  interface 
associated  to  intervention  parameters  in  the  scenario  editor,  while  Table  6  and  Table  7  provide 
additional  details  regarding  valid  values  and  a  description  of  every  single  parameter  and  intervention 
effects  respectively.  Note  that  interventions  can  either  influence  variables  through  a  default  relation,  or 
through  relations  that  are  activated  under  certain  conditions  that  depend  on  the  variables0  values 
(ElCondition  Instances!?]). 
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Interventions 
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Description  ve  effect  on  population  allegiance  when  cultural  understanding  is  low  [V] 


Figure  26  -  Interventions  parameters 


Table  6  -  Details  of  basic  Interventions  parameters 


Name 

Type 

Valid  values 

Description 

MinValue 

Integer 

Any  valid 
lower 

MaxValue 

Integer 

than 

The  minimum  value  for  that  intervention.  Note 
that  negative  minimum  values  are  special  because 
the  neutral  intervention  happens  when  the  value 
is  zero.  Therefore,  negative  interventions  are 
tagged  accordingly  (EH-/-0sign)  in  the  user  interface 

MaxValue 

Integer 

Any  valid 

Integer 

The  maximum  value  for  that  intervention 
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larger  than 

MinValue 

Description 

String 

Any  valid  String 

A  description  of  that  intervention,  which  is  shown 
as  the  tooltip  of  the  interventions  label  in  the 
main  user  interface 

Hidden 

List<String> 

Any  valid  list  of 

Intervention  effects  of  specified  variables  are 

Variables 

Strings  containing 
variable  IDs 

systematically  hidden  (i.e.,  not  shown  to 
participants).  Empty  list  by  default 

HiddenDetails 

List<String> 

Any  valid  list  of 

Intervention  effects  relation  details  of  specified 

Variables 

Strings  containing 
variable  IDs 

variables  are  systematically  hidden  (i.e.,  the 
presence  of  relations  are  shown,  but  not  the 
specific  effects).  Empty  list  by  default 

Order 

Integer 

Any  valid  Integer 

Intervention  effects  are  ordered  in  the  user 
interface  according  to  the  order  specified.  Lower 
values  are  sorted  first 

Label 

String 

Any  valid  String 

An  intervention  effect  is  identified  with  this  label 

in  the  user  interface 

Table  7 

Details  of  parameters  associated  to  Intervention  Effects 

Name 

Type 

Valid  values 

Description 

Description 

String 

Any  valid  String 

A  description  of  this  intervention  effect  that  is 
shown  when  the  user  clicks  the  0Details0  button  in 

the  relations  chart 

Values 

List<lnteger> 

Any  valid  list  of 
Integers 

Specifies  the  interventions  influence  on  the 
current  variable.  The  size  of  that  list  should  be 
0MaxValue  0  MinValue  +  10,  except  for  dummy 
interventions  that  can  be  of  any  size 

Noise 

Integer 

0,... 

Random  noise  added  to  the  intervention  value. 

Default:  0 

Delay 

Integer 

0,... 

The  delay  before  the  influence  is  actually  applied 
on  the  variables  value 

Hidelnfluence 

Boolean 

True,  False 

True:  hides  the  intervention  effect  from  the  list 
displayed  to  the  user;  False:  adds  the  intervention 
effect  in  the  list  (default) 

HideDetails 

Boolean 

True,  False 

True:  disables  showing  the  relation  chart  of 
variable  influence  as  a  function  of  the  intervention 
value;  False:  enables  showing  the  relation  (default) 

Dummy 

Boolean 

True,  False 

True:  the  intervention  effect  is  displayed  to  the 
user  but  not  taken  into  account  in  the  simulation; 
False:  this  is  a  real  intervention  effect  (default) 

Order 

Integer 

Any  valid  Integer 

The  order  in  which  intervention  effects  will  be 
presented  in  the  dropdown  menu.  Lower  values 
are  sorted  first 

Condition 

String 

Any  Javascript 

statement  that 

returns  a  Boolean 

The  condition  under  which  a  conditional 

intervention  effect  is  considered  rather  than  the 

default  values  relation 
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Label 

String 

Any  valid  String 

A  label  that  will  be  displayed  instead  of  the  actual 
condition  when  a  user  requests  for  details  about  a 
condition  instance.  Default:  the  actual  condition 

Values 

List<lnteger> 

Any  valid  list  of 
Integers 

Same  as  default  values  but  for  a  conditional 

intervention  effect.  Default  values  relation  is 

considered  when  all  conditions  return  false 

3.3.2  Variable  Influence  on  Action  Points 


In  a  typical  scenario,  the  number  of  action  points  to  be  dispatched  by  the  user  will  change  according  to 
the  state  of  the  situation.  The  contribution  of  each  variable  to  this  number  is  specified  in  the  SAction 
Pointsmtab  of  the  scenario  editor.  Parameters  available  are  shown  in  Figure  27,  and  additional  details 
can  be  found  in  Table  8. 
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Order  I  |r| 


Figure  27  i  Variable  influence  on  action  points 


Table  8  -  Details  of  variable  influence  on  action  points  parameters 


Name 

Type 

Valid  values 

Description 

Values 

List<lnteger> 

Any  valid  list  of 
Integers 

List  that  specifies  the  contribution  of  a  given 
variable  to  the  number  of  action  points  as  a 
function  of  its  value.  The  size  of  that  list  should  be 
Eh/ariable.MaxValue  13  variable. MinValue  +  10, 
except  for  dummy  contributions  that  can  be  of  any 
size 

Noise 

Integer 

0,... 

Random  noise  added  to  the  influence  value. 

Default:  0 

Hidelnfluence 

Boolean 

True,  False 

True:  hides  the  action  point  provenance  from  the 
list  displayed  to  the  user;  False:  adds  the  action 
point  provenance  to  the  list  (default) 
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HideDetails 

Boolean 

True,  False 

True:  disables  showing  the  relation  of  action  points 
contribution  as  a  function  of  the  variables  value; 
False:  enables  showing  the  relation  (default) 

Dummy 

Boolean 

True,  False 

True:  the  action  point  provenance  is  simply 
displayed  to  the  user  and  not  taken  into  account  in 
the  calculations;  False:  this  is  a  real  action  points 
provenance  (default) 

Description 

String 

Any  valid  String 

A  description  of  that  action  points  provenance  that 
is  shown  when  the  user  clicks  the  0Details0  button 

in  the  relation  chart 

Order 

Integer 

Any  valid  Integer 

Action  points0provenances  are  organized  in  the 
user  interface  according  to  the  order  specified. 
Lower  values  are  sorted  first 

3.3.3  Player-Specific  Representation  of  Variables 


In  a  scenario  involving  multiple  participants,  variables  may  not  have  the  same  meaning  for  every 
participant.  For  that  purpose,  a  player-specific  representation  (green,  orange  and  red  ranges)  can  be 
defined  for  every  variable,  which  is  different  for  every  participant  (in  the  action  points  tab).  Similarly,  the 
uncertainty  that  is  displayed  around  a  variable  can  be  specified  for  every  user.  Specific  representations 
values  are  defined  in  the  0Action  pointsH  tab  of  the  scenario  editor.  Figure  28  shows  a  typical 
configuration  of  a  player-specific  representation  in  the  scenario  editor.  Clicking  on  the  0Add0  button 
asks  the  user  for  which  variable  he  wants  to  define  a  new  player-specific  representation  of  variable. 
Clicking  on  the  0Remove0  button  removes  the  selected  specific  representation.  The  signification  of 
parameters  is  the  same  as  those  established  in  Table  2. 
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Figure  28  0  Player-specific  representation  of  variables 
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3.4  Description  of  Custom  Events 


Custom  events  allow  a  scenario  developer  to  define  events  that  will  be  activated  under  specific 
conditions.  Conditions  are  expressed  in  Javascript  or  using  a  custom  class  instance  that  implements 
Conditionl.  Custom  events  are  extremely  versatile  in  terms  of  configuration,  because  they  can  be 
activated  on  a  specific  turn  or  not,  and  activated  at  the  beginning  or  at  the  end  of  a  turn.  When  an  event 
is  not  activated  on  a  specific  turn,  it  can  be  executed  several  times.  In  order  to  limit  the  number  of 
possible  executions,  a  0repetitions0  parameter  can  be  specified,  which  will  allow  the  custom  event  to  be 
executed  0repetitions0  times  (or  no  limit  when  0repetitions  =  -10).  The  effect  of  an  actual  event  can 
either  be  specified  using  Javascript  code  that  will  have  access  to  the  current  variables  value.  Those 
values  can  be  manipulated  in  the  code.  If  Javascript  is  not  sufficiently  expressive,  custom  classes  can  be 
developed  that  will  have  access  to  every  variable  in  the  simulation.  It  should  be  noted  that  values  should 
be  manipulated  with  care  because  this  can  cause  potential  inconsistencies  in  the  simulation. 

Figure  29  shows  a  typical  configuration  for  a  custom  event.  In  this  case,  an  instance  of  the  Insurgents 
Strategy  Execution0  class  is  created  and  evaluated  at  the  end  of  every  turn.  This  class  implements  a 
strategy  for  the  insurgents;  it  tries  to  evaluate  the  state  of  the  situation  on  the  next  turn  without  the 
blue  force  intervention,  and  chooses  the  red  intervention  that  will  be  the  most  favourable  for  the 
insurgents0side.  Therefore,  variables0values  are  manipulated  by  the  custom  code  execution. 

As  for  the  scenario  editor,  a  custom  event  is  added  by  clicking  on  the  0Add0  button  and  removed  by 
clicking  on  the  0Remove0  button.  More  details  about  every  single  parameter  associated  to  custom 
events  are  provided  in  Table  9. 
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Figure  29  -  Custom  events  parameters 
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Table  9  -  Details  of  the  Custom  Events  parameters 


Name 

Type 

Valid  values 

Description 

Code 

String 

Any 

Javascript 

statement 

valid 

The  Javascript  statement  manipulates  variables  and 
has  access  to  every  instantiated  variable,  referenced 
with  their  ID.  Sample  code:  0variablel  =  variablel  + 

40 

Code. custom 

String 

Any  valid 

name 

implements 

Executionl 

class 

that 

An  implementation  of  Executionl  allows  for  more 
sophisticated  variables  manipulation  that  cannot  be 
expressed  with  simple  Javascript  code.  Custom  code 
has  priority  over  normal  code 

Turn 

Integer 

-1,... 

The  turn  in  which  the  custom  event  will  be  executed. 
0-10when  turn  number  does  not  matter  (default) 

Condition 

String 

Any  valid 

Javascript 
statement  that 

returns  a  Boolean 

The  Javascript  statement  has  access  to  every 
instantiated  variable,  referenced  with  their  ID,  and 
should  return  a  Boolean.  When  True,  the  custom 
event  is  executed;  when  False,  nothing  happens 

Condition. 

custom 

String 

Any  valid 

name 

implements 

Conditionl 

class 

that 

An  implementation  of  Conditionl  allows  for  more 
sophisticated  conditions  specification  that  cannot  be 
expressed  with  simple  Javascript  code.  Custom 
condition  has  priority  over  normal  condition 

Text 

String 

Any  valid  String 

Information  text  that  is  displayed  to  users  when  the 
custom  event  is  executed.  By  default,  does  not  show 
any  text.  The  text  is  shown  to  every  user 

Before  Turn 

Boolean 

True,  False 

True:  the  custom  event  will  be  executed  before  the 
turn;  False:  the  custom  event  will  be  executed  after 
the  turn  (default) 

Repetitions 

Integer 

-1,... 

When  no  turn  is  specified,  the  code  can  be  executed 
several  times.  This  parameter  limits  the  number  of 
repetitions.  0-10for  no  limit 

Order 

Integer 

Any  valid  Integer 

When  several  custom  events  in  the  same  turn,  this 
parameter  sets  the  order  in  which  they  will  be 
evaluated/executed.  Lower  values  are  ordered  first 

VisibleTo 

List<String> 

Any  valid 
Strings 

list  of 

List  of  participant  Ids  to  which  the  text,  if  not  empty, 
will  be  shown.  Default:  0[ a  1 1  ] 0 

3.5  Description  of  Information  Text 

CODEM  can  notify  users  about  what  is  happening  in  the  situation  or  create  prompts  that  request  player 
input  via  Information  TextEL  Corresponding  data  structures  can  be  specified  in  the  0lnfo  Text0tab  of  the 
scenario  editor.  They  include  information  messages  that  are  shown  to  the  user,  or  text  prompts  in  which 
the  participant  has  to  enter  a  value.  After  being  shown  to  the  user  as  a  popup,  the  text  can  be  added  (or 
not)  to  the  appropriate  category  of  a  text  pane  which  remains  accessible  at  any  time. 
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Information  text  is  typically  configured  in  the  scenario  editor,  as  shown  in  Figure  30.  In  this  example,  a 
prompt  will  be  shown  to  the  user  with  the  question  ElWhen  are  you  going  to  win?0  at  the  beginning  of 
turn  5  and  will  be  added  to  the  ^Prediction!?]  category  in  the  info  tab.  More  details  on  the  signification  of 
every  parameter  can  be  found  in  Table  10. 
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Figure  30  -  Info  text  parameters 


Table  10  -  Details  of  Info  Text  parameters 


Name 

Type 

Valid  values 

Description 

Text 

String 

Any  valid  String 

The  text  that  is  shown  to  the  user 

Turn 

Integer 

-1,... 

The  turn  at  which  the  info  text  should  be  displayed.  -1 
displays  the  info  text  each  turn 

Condition 

String 

Any  valid 

Javascript 

statement 

A  Javascript  condition  that  has  to  be  true  in  order  for 
the  info  text  to  be  displayed.  Default:  no  condition, 
activated  by  usual  mechanisms 

Display 

Boolean 

True,  False 

True:  shows  a  popup  to  the  user  before  adding  the 
text  to  the  info  tab  (default);  False:  hides  the  info  text 
popup  from  the  user,  but  shows  it  in  the  info  tab 

Prompt 

Integer 

0, 1,2 

0:  the  info  text  does  not  prompt  the  user  (default);  1: 
prompts  the  user  for  an  answer  and  writes  the  text 
and  answer  to  the  log  and  info  tab;  2:  prompts  the 
user  for  answer  but  only  writes  it  to  the  log  file 

Order 

Integer 

Any  valid 

Integer 

When  several  info  texts  are  specified  at  the  same 
moment  and  turn,  this  parameter  will  determine  their 
order  of  appearance.  Lower  values  are  sorted  first 

Moment 

Integer 

0,  1,  2,  3 

0:  info  text  is  shown  before  turn  (default);  1:  info  text 
is  shown  after  prediction;  2:  info  text  is  shown  after 
decision;  3:  info  text  is  shown  after  turn 

VisibleTo 

List<String> 

Any  valid  list  of 

The  participants  to  which  this  info  text  will  be 
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participants 

available.  Participants  are  referred  to  using  their  ID 

Category 

String 

Any  valid  String 

The  category  of  the  info  tab  in  which  the  current  info 
text  should  be  added 

Log 

Boolean 

True,  False 

True:  adds  the  info  text  to  the  log  (default);  False: 
does  not  add  the  info  text  to  the  log 

Timeout 

Integer 

0,... 

Number  of  milliseconds  after  which,  following  the 
right  moment,  the  info  text  will  be  shown  to  the  user. 
Default:  000 

3.6  Configuration  of  the  Scenario  Editor 


It  is  possible  to  configure  the  scenario  editor  via  an  XML  configuration  file  that  defines  every  single 
parameter  in  terms  of  its  name,  type  and  tooltip  text  that  appears  when  the  user  moves  the  mouse 
cursor  over  the  label.  The  configuration  file  is  located  in  0config/EditorConfig.xml0  relative  to  the  root 
directory  of  CODEM.  This  can  be  useful  to  change  the  editors  language  if  desired,  or  rename  some 
concepts  (change  turn  for  year  or  month)  or  expand  some  tooltips.  Even  though  every  single  parameter 
can  be  configured  via  this  file,  it  is  unadvised  to  do  so.  In  fact,  parameters  can  be  added  in  the 
0Scenario0  tab  without  any  consequence  on  the  simulation.  For  example,  in  one  extension  that  was 
implemented  in  CODEM,  there  was  a  need  to  add  the  insurgents  strategy0  parameter,  which  is  realized 
with  the  following  XML  snippet  placed  under  the  0Scenario0  element;  the  resulting  user  interface 
elements  in  the  scenario  editor  are  shown  in  Figure  31: 


<Group  nam e=  "  Insurgents  Strategy"  tooltip -"Specific  to  COIN  scenario"> 

<Param  name=" Insurgents . allocation"  typ e="string"  tool tip= " [Specific  to  COIN 
scenario]  Strength  of  insurgents'  strategic  strike" /> 

</Group> 


Insurgents  Strategy  (?) 


Insurgents. allocation  ’gent_forces  <  10){2;}else  {!;}  [Vi 


Figure  31  -  Insurgents  strategy  parameters 


It  should  be  noted  that  once  a  parameter  is  added  in  a  scenario,  some  Java  code  must  handle  it.  Such 
code  can  be  written  in  extensions,  as  described  in  the  following  section. 


3.7  Extensions 


CODEM  allows  simulating  situations  composed  of  variables  that  influence  one  another,  as  well  as 
interventions  that  are  controlled  by  the  user.  The  latter  can  be  completely  accomplished  without  writing 
a  single  line  of  code.  Although  a  certain  level  of  flexibility  is  available  with  the  use  of  Javascript  in 
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conditions  and  code  in  custom  events,  there  might  be  situations  in  which  more  complex  processing  is 
required.  For  that  purpose,  the  experimental  platform  contains  0hook0  interfaces  that  allow  for  loading 
custom  classes  into  the  platform  at  runtime.  Such  classes  should  be  developed  with  care  because  they 
can  introduce  modifications  to  the  dynamic  properties  of  agents  that  compose  a  simulation. 

Conditions  and  executions  that  can  accomplish  more  sophisticated  processing  for  specific  uses  have 
access  to  the  game  history  and  the  current  situation.  Extensions  can  be  defined  in  two  particular  areas: 
winning  &  losing  conditions  and  custom  events  (condition  and  execution).  The  two  interfaces  that  can 
be  implemented  are: 

ca.lti. image  see . scenariov2 . coin2 . hooks . ConditionI 

o  void  init  (Map<String,  Object>  paramet  ers);  Initialises  the  custom 

condition.  0parameters0  provides  a  set  of  static  scenario  parameters; 

o  boolean  evaluate (GameHistory  history  ,  Map<String,  0  bject> 
parameters,  DynamicParametersContainerl  dynamicParams ,  R  andoml 
random)  ;  ->  Evaluates  the  custom  condition  and  returns  true  when  the  condition  is 
met,  otherwise  false.  0history0  provides  the  entire  game  history  (variables  values  and 
decisions),  0parameters0  provides  a  set  of  static  scenario  parameters,  0dynamicParams0 
provides  a  set  of  dynamic  parameters  (parameters  that  can  be  modified  during  the 
simulation)  and  0random0  provides  a  random  number  generator, 
ca.lti. image  see . scenariov2 . coin2 . hooks . ExecutionI 

O  void  init  (Map<String,  Object>  paramet  ers);  Initialises  the  custom 

execution.  0parameters0  provides  the  set  of  static  scenario  parameters; 

O  Map<String,  Integer>  evaluate (GameHistory  history,  Map<String, 
Object>  parameters,  DynamicParametersContainerl  dynamicParams, 
Randoml  random)  ;  ->  Evaluates  the  custom  execution.  0history0  provides  access  to 
the  game  history,  0parameters0  provides  a  set  of  static  scenario  parameters, 
0dynamicParams0  provides  a  set  of  dynamic  parameters  (parameters  that  can  be 
modified  during  the  simulation)  and  0random0  provides  a  random  number  generator. 
Returns  a  map  of  relative  changes  that  should  be  applied  on  the  variables  values. 
Simulation  agents  (variables  and  action  points)  can  also  be  modified  directly  using  static 
object  instances;  this  feature  should  however  be  used  with  care.  For  example,  in  order 
to  modify  the  number  of  available  action  points,  update  the  0unusedActionPoints0 
dynamic  property. 

Another  type  of  extension  makes  it  possible  to  add  participants.  The  implementation  class  should  be 
specified  in  the  0Action  Points0tab  of  the  scenario  editor  using  the  0lmplementation0  parameter.  This 
extension  should  be  used  in  cases  where  the  participants  role  is  played  by  an  external  entity  (e.g. 
learning  algorithm,  another  implementation  of  the  user  interface).  Two  interfaces  can  be  implemented 
in  order  to  play  the  latter  role: 

ca . lti . image  see . scenariov2 . coin2 . ui . dispatch . UIDispatchAdapterl 

ca . lti . image  see . scenariov2 . coin2 . ui . dispatch . UIRemoteDispatchAdapterl 
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The  difference  between  the  two  interfaces  is  that  the  remote  one  has  to  implement  two  additional 
methods  (0reset0  and  0fini0)  so  that  several  instances  of  the  dispatcher  can  be  started  and  stopped 
successively.  Therefore,  the  implementer  should  make  sure  that  resources  are  cleared  when  0reset0  is 
called,  and  be  ready  for  the  Ul  dispatcher  to  be  initialized  again.  When  0fini0  is  called,  no  more  Ul  will  be 
created  and  the  simulator  will  terminate.  Additional  details  on  every  method  that  needs  to  be 
implemented  are  provided  in  Appendix  C. 

The  next  three  sections  describe  three  extensions  that  were  implemented  for  demonstration  purpose. 
The  first  one  implements  a  custom  execution  that  adds  a  certain  level  of  flexibility  to  insurgents  in  a 
counter  insurgency  scenario  (Section  3.7.1).  The  second  one  implements  a  custom  winning  condition 
that  triggers  when  the  prediction  errors  become  stable  (Section  3.7.2).  The  third  one  implements  an 
algorithm  for  finding  optimal  solutions  in  a  scenario  (Section  3.7.3). 

3.7.1  insurgents  Strategy  ^Extension 


This  extension  implements  a  strategy  for  insurgents  that  are  able  to  adapt  as  a  function  of  the  situation. 
Concretely,  insurgents  can  influence  the  situation  by  directly  changing  the  value  of  one  variable  per  turn 
(in  addition  to  having  other  behaviours  defined  as  mutual  influences,  which  can  change  using 
conditional  mutual  influences).  The  extent  of  this  influence  is  determined  by  the  actual  level  of 
insurgency,  and  is  evaluated  using  a  Javascript  statement.  The  context  associated  to  the  Javascript 
statement  contains  only  one  variable  identified  by  the  name  of  the  insurgent  forces  variables;  the 
statement  should  set  the  number  of  points  allocated.  For  example,  the  following  statement  has  the 
result  of  allocating  1  point  if  the  insurgency  level  is  smaller  or  equal  to  6,  2  points  if  the  insurgency  level 
is  smaller  or  equal  to  13  and  3  points  in  other  cases: 

if ( insurgency  <=  6){1;}  else  if ( insurgency  <=  13) {2;}  else  {3;} 

Insurgents  can  directly  influence  the  following  variables:  0Governance,0  0Population  Allegiance, 0 
0Media,0  Infrastructures, 0  0Criminality,0  and  0Local  Forces. 0  The  direct  influence  is  chosen  by 
simulating  what  should  happen  in  the  next  turn  if  the  blue  forces  would  not  intervene  in  the  situation, 
and  choosing  the  course  of  action  that  has  the  most  advantageous  outcome  for  the  insurgents0side. 

3.7.2  ^Stable  Prediction  ErrorSExtension 


This  extension  implements  a  winning  condition  that  is  triggered  when  a  participants  mean  prediction 
error  does  not  decrease  anymore  over  a  specified  time  window.  It  is  hypothesized  that  during  a 
mandate,  the  prediction  error  at  the  beginning  will  be  high,  and  will  decrease  down  to  a  certain  level  as 
turns  pass  and  the  participants  understanding  of  the  situation  increases.  So  this  is  basically  a  stopping 
criterion  when  asymptotic  anticipatory  performance  is  achieved  in  the  context  of  a  function  learning 
task. 
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This  extension  can  be  configured  using  parameters  defined  in  the  scenario  editor: 

0Anticipation.nblterationsForError0:  this  parameter  specifies  the  time  window  over  which  the 
prediction  error  will  be  calculated 

0Anticipation.stopCondition0:  this  parameter  specifies  the  stop  condition  expressed  in  Javascript 
that  should  terminate  the  mandate.  The  attributes  available  in  the  Javascript  context  are  the 
following: 

o  0slope0:  the  slope  of  prediction  error  over  a  window  of 

0Anticipation,nblterationsForError0  turns 
o  0currentError0:  the  mean  prediction  error  for  the  current  turn 
o  0iteration0:  the  current  iteration 

Figure  32  shows  how  the  mean  prediction  error  should  evolve  as  a  function  of  turn  time.  The  slope  is 
defined  over  a  time  window,  and  should  be  within  the  level  specified  in  the  stop  condition. 


Turn  number 


Figure  32  -  Mean  prediction  error  as  a  function  of  turn  number  showing  the  prediction  errors  slope  in  a  time  window 

3.7.3  Genetic  Algorithms  for  Finding  Optimal  Solutions 


This  extension  implements  a  hook  that  replaces  the  standard  user  interface  with  an  automatic  decision 
making  algorithm.  The  allocation  of  action  points  is  realized  via  a  genetic  algorithm  that  optimizes  a 
score  variable.  The  actual  genetic  algorithm  is  implemented  using  the  Evolver  Excel  add-on,  which  is 
configured  to  explore  the  decision  space  in  an  effective  manner.  Therefore,  a  software  infrastructure 
was  put  in  place  so  that  CODEM  can  communicate  with  Excel  in  order  to  retrieve  actions  points 
allocation  and  put  back  the  score  variable.  This  work  is  still  in  progress,  but  will  be  further  detailed  once 
results  are  available.  Since  the  hooking  mechanism  is  very  versatile,  it  would  also  allow  the  integration 
of  other  automatic  decision  algorithms  such  as  adversaries  or  collaborators. 
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4  Conclusion 


In  conclusion,  an  experimental  platform  that  supports  the  simulation  of  complex  situations  with  the 
system  dynamics  formalism  was  developed.  This  platform  allows  experimenters  to  study  human 
sensemaking  and  decision  making  in  a  systematic  fashion.  The  complex  situation  is  expressed  via  a 
scenario  editor  that  allows  modifying  every  single  parameter  straightforwardly.  Those  include 
parameters  associated  to  variables,  action  points  and  interventions,  custom  events  and  information 
texts.  A  complex  situation  can  be  built  without  the  need  for  users  to  write  any  Java  code.  However,  the 
platform  provides  software  hooks  that  allow  for  custom  classes  to  be  loaded  should  they  be  needed  for 
more  advanced  use. 

The  experimental  platform  also  provides  a  user  interface  that  allows  a  user  to  visualize  the  current 
status  of  a  situation,  make  predictions  about  the  state  of  variables  in  the  next  turn,  make  decisions  on 
interventions  that  influence  the  situation,  take  various  notes,  retrieve  information  about  the  past  states 
of  the  situation,  and  observe  the  changes  that  occurred  on  variables  during  a  turn.  In  order  to  facilitate 
the  experimenters  work,  log  files  record  actions  performed  by  the  user. 


LT|- September  2010 


43 


5  References 


Chein,  M.,  &  Mugnier,  M.  (2008).  Graph-based  Knowledge  Representation:  Computational  Foundations 
of  Conceptual  Graphs.  Springer  London. 

DEIrner,  D.  (1996).  The  logic  of  failure:  Recognizing  and  avoiding  error  in  complex  situations.  Reading, 
MA:  Addison-Wesley. 

Lizotte,  M.,  Bernier,  F.,  Mokhtari,  M.,  Boivin,  E.,  DuCharme,  M.  and  Poussart,  P.  (2008).  Image: 
Simulation  for  Understanding  Complex  Situations  and  Increasing  Future  Force  Agility.  The  26th  Army 
Science  Conference,  December  1-4,  Orlando,  FL. 

Sterman,  J.D.  (2000).  Business  Dynamics:  Systems  Thinking  and  Modeling  for  a  Complex  World,  Irwin 
McGraw-Hill,  Boston,  MA. 


LT|- September  2010 


44 


A.  Log  Files  Content  Description 


Two  types  of  log  files  are  recorded  during  a  mandate:  the  participants  log  and  the  game  log.  More 
details  are  available  in  the  following  sections. 

A.l  Participants  Log  Description 

The  human  log  contains  a  trace  of  which  actions  the  user  performed  during  a  turn.  The  file  name  of  the 
human  log  follows  this  pattern:  HYearMonthDay-HourMinuteSeconds-SimulationStartTime-User- 
ParticipantlD-SessionlD-GroupID 


Column 

Value 

Description 

MSG_TYPE 

ACTION_POINT_AVAILABLE 

The  number  of  action  points  available  at  the 
beginning  of  a  turn 

SIM TIME 

Integer 

The  simulation  time 

TARGET 

- 

VALUE 

Integer 

The  number  of  action  points 

LOG TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG_TYPE 

CONDITION 

.DETAILS. 

.CLOSE 

The  condition  details'  window  for 

current  chart  has  closed 

the 

SIM_TIME 

Integer 

The  simulation  time 

TARGET 

String 

The  selected  condition 

VALUE 

String 

The  details  about  the  condition 

LOG_TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG_TYPE 

CONDITION 

.DETAILS. 

.OPEN 

The  condition  details'  window  for 
current  chart  has  opened 

the 

SIM TIME 

Integer 

The  simulation  time 

TARGET 

String 

The  selected  condition 

U|- September  2010 


45 


VALUE 

String 

The  details  about  the  condition 

LOG TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG_TYPE 

CONFIDENCE 

Confidence  value  about  a  variable  has 
changed 

SIM TIME 

Integer 

The  simulation  time 

TARGET 

String 

Variable  name 

VALUE 

Integer 

The  confidence  value 

LOG TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG_TYPE 

DECISION 

An  intervention  changed  for  a  variable 

SIM TIME 

Integer 

The  simulation  time 

TARGET 

String 

Variable  where  more  or  less  action  points 
are  spent 

VALUE 

Integer 

Action  points  assigned  to  the  variable 

LOG_TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG TYPE 

DECISIONDONE 

The  user  has  made  his  decisions  for  the  turn 

SIM_TIME 

Integer 

The  simulation  time 

TARGET 

- 

VALUE 

- 

LOG_TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG TYPE 

FINAL DECISION 

The  final  value  for  an  intervention 

SIM_TIME 

Integer 

The  simulation  time 

TARGET 

String 

Intervention  for  which  decision  was  made 

VALUE 

Integer 

Action  points  assigned  to  the  intervention 

LOG_TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG TYPE 

FINAL PREDICTION 

The  final  value  for  a  prediction 

SIM_TIME 

Integer 

The  simulation  time 

TARGET 

String 

Variable  for  which  the  prediction  was  made 

VALUE 

Integer 

Prediction  made  for  variable 

LOG_TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG TYPE 

FINAL CONFIDENCE 

The  final  value  for  the  confidence 

SIM_TIME 

Integer 

The  simulation  time 

TARGET 

String 

Variable  for  which  the  confidence  was  set 

VALUE 

Integer 

The  confidence  value 

LOG_TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 
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MSG TYPE 

FINAL AP AVAILABLE 

The  final  value  of  action  points  available 

SIM_TIME 

Integer 

The  simulation  time 

TARGET 

Integer 

Final  value  of  action  points  available 

VALUE 

Integer 

Final  value  of  action  points  left 

LOG_TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG TYPE 

HIDE VARIABLE 

Variable's  outgoing  relations  are  hidden 

SIM_TIME 

Integer 

The  simulation  time 

TARGET 

String 

Variable  name 

VALUE 

- 

LOG_TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG_TYPE 

INFO 

New  information  added  in  the  information 

tab 

SIM TIME 

Integer 

The  simulation  time 

TARGET 

String 

If  info  text  was  a  prompt,  the  user's  answer 

VALUE 

String 

The  new  information  message 

LOG TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG TYPE 

NOTE 

The  user  added  a  note 

SIM TIME 

Integer 

The  simulation  time 

TARGET 

String 

The  note  tab 

VALUE 

String 

The  note 

LOG TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG_TYPE 

PREDICTION 

The  user  changed  its  prediction  for  a  variable 
value 

SIM_TIME 

Integer 

The  simulation  time 

TARGET 

String 

Variable  name 

VALUE 

Integer 

The  predicted  value 

LOG_TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG_TYPE 

PREDICTION_DONE 

The  user  has  made  his  predictions 

SIM_TIME 

Integer 

The  simulation  time 

TARGET 

- 

VALUE 

- 

LOG_TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG_TYPE 

RECEIVE_ACTION_POINT 

Received  a  number  of  action  points  from 
another  participant 
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SIM TIME 

Integer 

The  simulation  time 

TARGET 

Integer 

Total  number  of  action  points  available 

VALUE 

Integer 

Number  of  action  points  received 

LOG TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG_TYPE 

RELATION 

m 

_ i 

< 

1 — 

LU 

O 

i 

CLOSE 

Details  window  closed 

SIM TIME 

Integer 

The  simulation  time 

TARGET 

String 

Title  of  the  relation  window 

VALUE 

String 

Details  message 

LOG TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG_TYPE 

RELATION 

m 

_ i 

< 

1 — 

LU 

Q 

1 

OPEN 

Details  window  opened 

SIM TIME 

Integer 

The  simulation  time 

TARGET 

String 

Title  of  the  relation  window 

VALUE 

String 

Details  message 

LOG TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG_TYPE 

SEND_ACTION_POINT 

Send  a  number  of  action  points  to  another 

participant 

SIM_TIME 

Integer 

The  simulation  time 

TARGET 

String 

The  participant  to  which  action  points  are 
sent 

VALUE 

Integer 

Number  of  action  points  sent 

LOG TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG_TYPE 

SHOW_VARIABLE 

Variable's  outgoing  relations  are  shown 

SIM TIME 

Integer 

The  simulation  time 

TARGET 

String 

Variable  name 

VALUE 

- 

LOG TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG_TYPE 

TAB_ACTIVATED 

A  new  tab  is  displayed 

SIM TIME 

Integer 

The  simulation  time 

TARGET 

String 

Title  of  the  window  or  frame  containing  the 
tabs 

VALUE 

String 

Title  of  the  tab 

LOG_TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG_TYPE 

TAB_CREATED 

A  tab  is  created 

SIM_TIME 

Integer 

The  simulation  time 

TARGET 

String 

Title  of  the  window  or  frame  containing  the 
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tabs 

VALUE 

String 

Title  of  the  tab 

LOG_TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG_TYPE 

TAB_ELAPSED_TIME 

Time  elapsed  in  a  tab  before  going  to 
another.  It  includes  time  spent  in  sub 
windows  such  as  a  chart 

SIM TIME 

Integer 

The  simulation  time 

TARGET 

String 

Title  of  the  tab 

VALUE 

Integer 

Elapsed  time  in  milliseconds 

LOG TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG TYPE 

TAB REMOVED 

A  tab  is  removed 

SIM TIME 

Integer 

The  simulation  time 

TARGET 

String 

Title  of  the  window  or  frame  containing  the 
tabs 

VALUE 

String 

Title  of  the  tab 

LOG TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG_TYPE 

TAB_TOTAL_ELAPSED_TIME 

Time  spent  in  a  tab  for  the  entire  mandate 

SIM TIME 

Integer 

The  simulation  time 

TARGET 

String 

Title  of  the  tab 

VALUE 

Integer 

Elapsed  time  in  milliseconds 

LOG TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG_TYPE 

TAB_TOTAL_FREQUENCY 

The  total  number  of  times  a  tab  was 

consulted 

SIM_TIME 

Integer 

The  simulation  time 

TARGET 

String 

Title  of  the  tab 

VALUE 

Integer 

Number  of  times  the  tab  was  consulted 

LOG_TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG TYPE 

TAB TURN ELAPSED TIME 

Time  spent  in  a  tab  for  the  entire  turn 

SIM_TIME 

Integer 

The  simulation  time 

TARGET 

String 

Title  of  the  tab 

VALUE 

Integer 

Elapsed  time  in  milliseconds 

LOG_TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG TYPE 

TIME DISPLAYED CHANGE 

Time  displayed  in  the  user  interface 

SIM_TIME 

Integer 

The  simulation  time 

TARGET 

String 

The  tab  title  where  a  displayed  time  change 
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occurs 

VALUE 

Integer 

The  actual  displayed  simulation  time 

LOG_TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG_TYPE 

TURN_DONE 

The  moment  when  0next  turn®  button  is 
pressed 

SIM TIME 

Integer 

The  simulation  time 

TARGET 

- 

VALUE 

Integer 

Elapsed  time  in  milliseconds  since  beginning 
of  the  turn 

LOG_TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG_TYPE 

TURN_ELAPSED_TIME 

Time  elapsed  for  the  entire  turn 

SIM_TIME 

Integer 

The  simulation  time 

TARGET 

- 

VALUE 

Integer 

Elapsed  time  in  milliseconds 

LOG_TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG_TYPE 

WINDOW_ACTIVE_CONDITION 

Change  the  active  condition  for  a  chart  with 
conditions 

SIM_TIME 

Integer 

The  simulation  time 

TARGET 

String 

The  condition  activated 

VALUE 

- 

LOG_TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG TYPE 

WINDOW CLOSE 

A  window  has  closed 

SIM_TIME 

Integer 

The  simulation  time 

TARGET 

String 

Title  of  the  window 

VALUE 

- 

LOG_TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG TYPE 

WINDOW ELAPSED TIME 

Time  spent  in  a  window 

SIM_TIME 

Integer 

The  simulation  time 

TARGET 

String 

Title  of  the  window 

VALUE 

Integer 

Elapsed  time  in  milliseconds 

LOG_TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG TYPE 

WINDOW OPEN 

A  window  has  opened 

SIM_TIME 

Integer 

The  simulation  time 

TARGET 

String 

Title  of  the  window 

VALUE 

- 
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LOG TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG_TYPE 

WINDOW. 

.TOTAL. 

_ELAPSED_TIME 

Total  time  spent  in  a  window  in  a  mandate 

SIM TIME 

Integer 

The  simulation  time 

TARGET 

String 

Title  of  the  window 

VALUE 

Integer 

Time  in  milliseconds 

LOG TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG_TYPE 

WINDOW. 

.TOTAL. 

.FREQUENCY 

Total  number  of  times  a  window  was  open 

SIM TIME 

Integer 

The  simulation  time 

TARGET 

String 

Title  of  the  window 

VALUE 

Integer 

Number  of  times 

LOG TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG_TYPE 

WINDOW. 

.TOTAL. 

_PROP_VISITED 

Proportion  of  windows  that  were  visited 

SIM TIME 

Integer 

The  simulation  time 

TARGET 

String 

The  type  of  window  (or  global) 

VALUE 

Float 

Proportion  of  windows  visited  for  type 

LOG TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG_TYPE 

WINDOW. 

_TURN_ 

ELAPSED_TIME 

Total  time  spent  in  a  window  in  a  turn 

SIM TIME 

Integer 

The  simulation  time 

TARGET 

String 

Title  of  the  window 

VALUE 

Integer 

Time  in  milliseconds 

LOG_TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

A.2  Game®  Log  Description 

The  game  log  only  contains  final  values  for  a  turn  (i.e.  if  the  user  changes  his  predictions  or  decisions 
multiple  times  during  a  turn,  only  the  final  prediction/decision  will  be  logged).  The  file  name  of  the  game 
log  follows  this  pattern:  GYearMonthDay-HourMinuteSeconds-SimulationStartTime 


Column 

Value 

Description 

MSG_TYPE 

FILENAME 

The  current  file  name 

SIM TIME 

Integer 

The  simulation  time 

VAR_NAME 

- 

- 

VALUE 

String 

The  current  file  name 

USER 

- 
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LOG TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG_TYPE 

VARIABLE 

Variable  value 

SIM TIME 

Integer 

The  simulation  time 

VAR NAME 

String 

The  variable  name 

VALUE 

Integer 

The  variable  value 

USER 

- 

LOG TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

LOG_TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG TYPE 

PREDICTION 

Variable  value 

SIM_TIME 

Integer 

The  simulation  time 

VARIABLE 

String 

The  variable  name 

VALUE 

Integer 

The  variable  predicted  value 

USER 

String 

The  user  id 

LOG TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG_TYPE 

UNCERTAIN_VARIABLE 

The  variable's  value  has  uncertainty 

SIM TIME 

Integer 

The  simulation  time 

VAR NAME 

String 

The  variable  name 

VALUE 

Integer 

The  uncertain  variable's  value 

USER 

String 

The  user  id 

LOG TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG TYPE 

PREDICTION ERROR 

Prediction  error  value 

SIM TIME 

Integer 

The  simulation  time 

VARIABLE 

String 

The  variable  name 

VALUE 

Integer 

The  variable  prediction  error  value 

USER 

String 

The  user  id 

LOG_TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG TYPE 

CONFIDENCE 

Confidence  value 

SIM_TIME 

Integer 

The  simulation  time 

VARIABLE 

String 

The  variable  name  (or  global  if  only  one) 

VALUE 

Integer 

The  prediction's  confidence  value 

USER 

String 

The  user  id 

LOG TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG_TYPE 

END_TURN 

The  end  iteration 

SIM_TIME 

Integer 

The  simulation  time 
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VARIABLE 

- 

VALUE 

- 

USER 

String 

The  user  id 

LOG TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

MSG_TYPE 

END_STATUS 

The  end  of  mandate  status 

SIM TIME 

Integer 

The  simulation  time 

VARIABLE 

- 

VALUE 

String 

The  end  status  (WIN,  LOSE,  MAX TURN) 

USER 

String 

The  user  id 

LOG_TIMESTAMP 

Date 

Timestamp  of  the  log  message  creation 

A.3  Summary  Logs 

The  summary  logs  contain  final  values  for  each  turn  in  the  form  of  a  history.  Six  types  of  files  are 
generated:  variables,  confidence,  decisions,  human,  prediction  error  and  predictions.  The  file  name  of 
the  summary  log  follows  this  pattern:  SYearMonthDay-HourMinuteSeconds-SimulationStartTime- 
SummaryLogType.  For  each  summary  log  type,  each  column  contains  values  for  the  corresponding  turn: 

Variables:  one  row  per  variable;  each  column  for  the  variable  value 

Confidence:  one  row  per  variable,  or  only  one  for  global  confidence;  each  column  for  the 
confidence  value 

Decisions:  one  row  per  intervention;  each  column  for  the  number  of  action  points  allocated 
Human:  one  row  for  prediction,  notes,  relations,  decision,  info,  situation,  one  row  for  every 
open  window  and  one  row  for  time  needed  to  make  decisions,  predictions  and  complete  a 
single  turn;  each  column  contains  the  total  number  of  milliseconds  spent  at  performing  the 
corresponding  operation 

Prediction  error:  one  row  per  variable;  each  column  contains  the  prediction  error 
Prediction:  one  row  per  variable;  each  column  contains  the  prediction 
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B.  Text  Labels  of  the  User 
Interface 


In  order  to  create  a  new  resource  bundle,  simply  create  a  new  file  in  the  EconfigEI  directory  with  the 
following  nomenclature:  CODEMLabels_[language]_[country]_[variant],  E.g.  CODEMLabels_en_US_slang 

•  language:  a  valid  ISO  Language  Code  (http://www.loc.gov/standards/iso639-2/englangn.html) 
(default:  en) 

•  country:  (optional)  a  valid  ISO  Country  Code  (http://www.iso.ch/iso/en/prods- 

services/iso3166ma/02iso-3166-code-lists/list-enl.html)  or  empty 

•  variant:  (optional)  anything  you  want,  for  example  you  could  have  a  variant  named  "slang" 

In  order  to  adjust  the  latter  properties,  simply  add  a  corresponding  property  to 
0config/CODEM.properties0. 

Such  a  file  should  contain  every  single  text  label,  as  described  in  the  following  table. 


Parameter  Name 

Description 

Default  Value 

done 

Label  on  the  GDdoneEl  button  in  decision  and 
prediction  tabs 

Done 

not_available 

Text  shown  when  a  variable  is  not  available  in  the 

situation  tab 

N/A 

show 

Label  on  the  0show@  button  in  the  decision  tab 
that  pops  up  relations  graph 

Show 

commit 

Label  on  the  0commit0  button  in  the  notes  tab  that 

adds  new  text  to  the  current  notes 

Commit 

default 

Identifies  the  default  relation  in  the  relations 
graphs 

default 

info.title 

Title  of  the  info  tab 

Info 

info.turn 

Turn  label  in  the  info  text  prompts 

Turn 

info.question abbreviation 

Label  that  identifies  a  prompt  question 

Q 

info.answer abbreviation 

Label  that  identifies  a  prompt  answer 

A 

info. history 

Title  for  the  0diagram@tab  in  info  tab 

Diagram 
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info. default 

Title  for  the  0messages0tab  in  the  info  tab 

Messages 

info. summary 

Title  for  the  0history0tab  in  the  info  tab 

History 

info.end of turn 

Title  for  the  0feedbacks0tab  in  the  info  tab 

Feedbacks 

info.summary variables 

Title  for  the  0variables0group  in  the  summary  tab 

Variables 

info.summary decisions 

Title  for  the  0decisions0group  in  the  summary  tab 

Decisions 

note.title 

Title  for  the  notes  tab 

Notes 

note.default tab 

Title  for  the  0default0tab  in  the  notes  tab 

Default 

note .  n  e  w ta  b n  a  m  e 

Prompt  when  creating  a  new  tab  in  notes  tab 

New  tab  name? 

note.cannot_remove_default 

Notification  to  user  that  it  is  impossible  to  remove 

Cannot  remove 

tab 

default  tab 

default  tab... 

note.really remove tab 

Asks  user  for  confirmation  of  removing  tab 

Really  remove  tab 

Do  you  want  to 

note.really_commit 

Asks  user  to  really  commit  note  when  changing  tab 

commit  your 

note? 

note.really commit title 

Title  for  popup  message  to  commit  note 

Commit  note? 

note.turn number 

Label  for  turn  number  mention 

turn  # 

situation.title 

Title  for  situation  tab 

Situation 

situation.turn number 

Turn  number  shown  in  situation  tab 

Turn# 

situation.  next turn 

Label  of  the  0next  turn0  button 

Next  turn 

situation.  slider name 

History  time  slider  in  the  situation  tab 

Situation  history 

situation.  current value 

Tooltip  of  the  current  value  in  the  situation  tab 

Current  value 

Light  gray 

situation.  mediating_variables 
Jegend 

Legend  for  describing  mediating  variables 

background  = 

mediating 

variable 

situation. agent_variables_leg 
end 

Legend  for  describing  agent  variables 

Dark  gray 

background  = 

agent  variable 

situation.  remaining_turn_tim 

e 

Legend  for  remaining  turn  time 

Remaining  turn 
time 

situation.  remaining_decision 
time 

Legend  for  remaining  decision  time 

Remaining 
decision  time 

relation.title 

Relations  tab  title 

Relations 

relation.  show hide 

Variables  visibility  title 

Show  /  Hide 

relation.  show all 

Show  all  variables  button  label 

Show  all 

relation.  hide all 

Hide  all  variables  button  label 

Hide  all 

Cannot  init 

scripting  engine... 

relation.javascript_error 

Error  message  when  scripting  engine  is  unavailable 

conditional 

influence  will  not 

be  available 

relation. line_creation_error 

Error  message  when  a  relation  line  could  not  be 
built 

Could  not  build 

line... 

relation. instructions 

Legend  that  is  shown  in  the  relations  tab 

Click  on  arrows  to 

view  relations 
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prediction. title 

Title  of  the  prediction  tab 

Prediction 

prediction.  Iegend current 

Legend  shown  for  the  current  value 

Current  value 

prediction.  Iegend_current_a 
bbreviation 

Abbreviation  of  the  current  value  text  field 

C 

prediction.  legend prediction 

Legend  shown  for  the  prediction 

Prediction 

prediction.  legend_prediction 
abbreviation 

Abbreviation  of  the  prediction  value  text  field 

P 

prediction.  legend confidence 

Legend  shown  for  the  confidence 

Confidence 

prediction.  predicted_value_t 
ooltip 

Tooltip  shown  for  the  predicted  value  text  field 

Predicted  value 

prediction. current_value_too 
Itip 

Tooltip  shown  for  the  current  value  text  field 

Current  value 

prediction. confidence tooltip 

Tooltip  shown  for  the  confidence  value  text  field 

Confidence 

prediction. confidence short 

Short  title  for  confidence  radio  buttons 

Conf. 

prediction.  request_numeric 

Notification  when  wrong  value  is  entered  in 
prediction  text  field 

Please  enter 

numeric  value.. 

a 

prediction.  request_betweenl 

Notification  for  user  entering  a  specific  value 
(parti) 

Please  enter 

value  between 

a 

prediction.  request_between2 

Notification  for  user  entering  a  specific  value 
(part2) 

and 

prediction.  request_between3 

Notification  for  user  entering  a  specific  value 
(part3) 

decision.title 

Title  for  decision  tab 

Decision 

decision.  action_pts_available 

Title  for  number  of  available  action  points 

Action  points 

available 

decision. current_interventio 

n 

Title  for  current  intervention  entries 

Current 

intervention 

decision.variable_contributio 

n_desc 

Title  for  contribution  of  variables  to  action  points 

Contribution 

variables 
action  points 

of 

to 

decision. chart_var_on_action 
pts.titlel 

Title  for  contribution  chart  (parti) 

Contribution  of 

decision. chart_var_on_action 
pts.title2 

Title  for  contribution  chart  (part2) 

on  action  points 

decision. chart_var_on_action 
pts.y title 

Y  axis  title  for  contribution  chart 

Contribution 
action  points 

an 

decision. intervention_effects 

Title  for  effects  of  intervention 

Effects 

intervention 

of 

decision. chart_var_on_var.  tit 
lei 

Title  for  intervention  effects  chart  (parti) 

Influence  of 

decision. chart_var_on_var.  tit 
Ie2 

Title  for  intervention  effects  chart  (part2) 

on 

decision. chart_var_on_var.y_ 
title 

Y  axis  title  for  intervention  effects  chart 

Influence  on 

decision.  slider name 

Title  for  decision  time  slider 

Decision  history 

decision. share_AP_with 

Title  for  action  points  sharing 

Share  AP  with 
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decision. share send 

Label  for  0send  action  points0  button 

Send 

decision. unavailable_relation 

Message  to  the  user  when  clicking  on  a  relation 
that  is  not  available  for  details 

Relation  details 

unavailable... 

chart.delay 

Delay  label  in  charts 

Delay 

chart.condition 

Condition  label  in  charts 

Condition 

chart.details 

Label  for  0details0  button  in  charts 

Details 

chart. unavailable_condition 

Label  shown  when  a  condition  is  unavailable 

Unavailable 

condition 

chart.active condition 

Label  for  indicating  the  active  condition 

ACTIVE 

endmandate.variables_select 

Title  in  variables  selection  for  end  of  mandate 

Variables 

ion 

summary 

selection 

endmandate. title 

Title  for  end  of  mandate  summary  dialog 

End  of  mandate 

summary 

endmandate.x title 

X  axis  title  for  end  of  mandate  dialog 

Turn 

endmandate. y title 

Y  axis  title  for  end  of  mandate  dialog 

Value 

endmandate.  all var 

Show  all  variables  in  end  of  mandate 

All 

endturn. title 

Title  for  end  of  turn  summary  dialog 

End  of  turn 

summary 

endturn. changes 

Title  for  changes  end  of  turn  summary  dialog 

Changes 

endturn.  prediction_error 

Title  for  prediction  error  end  of  turn  summary 
dialog 

Prediction  error 

endturn. next 

Label  for  0next0  button  in  end  of  turn  dialog 

Next 

endturn. back 

Label  for  0back0  button  in  end  of  turn  dialog 

Back 

endturn.  Iegend_new_value_ 
abbreviation 

Label  for  new  value  in  prediction  error 

N 

endturn.  Iegend new value 

Legend  for  new  value  in  prediction  error 

New  value 

Move  mouse  over 

endturn.  changes_instructions 

Instructions  for  changes  dialog  in  end  of  turn 
dialog 

a  variable  to 

visualize  details 
on  changes 

endturn. intervention of 

Title  for  other  participants0interventions 

Interventions  of 

turntransition.title 

Title  for  turn  transition  dialog 

Turn  transition 

turnwait.  title 

Title  when  waiting  for  other  participants 

Waiting  for  other 
participants 

main.you win 

Default  message  when  winning 

You  win!!! 

main.youjose 

Default  message  when  losing 

You  lose!!! 

main.end_mandate 

Default  message  when  end  of  mandate 

End  of  mandate 

LT|- September  2010 


57 


C.  Details  of  the 

lEJIDispatchAdapterl  ^Interface 


Here  is  the  Javadoc  associated  to  the  UIDispatchAdapterl  interface  that  one  needs  to  implement  in 
order  to  build  a  functional  participant.  Note  that  some  are  optional  if  you  inherit  from 
UIDispatchAdapterA.  They  are  marked  with  **  sign. 


void  initLabels ( j ava . lang . String [ ]  actionPointLabels , 
j ava . lang . String [ ]  variablelDs, 
j  ava . lang . String [ ]  variable Labe Is , 
j  ava . lang . String [ ]  variableDe script ions , 
j  ava . util . Map< j  ava . lang . String, 

j  ava . util . Lis t< j ava . lang . String>> 
variablesQuali tiers ) 

Init  the  action  points,  variable  IDs  and  variable  labels  in  the  main  Ul  frame. 

Parameters: 

actionPointLabels  -  labels  associated  to  every  action  point.  The  order  is  important 
variablelDs  -  IDs  associated  to  variables.  The  order  is  important 
variable  Labe  Is  -  Labels  associated  to  variables.  The  order  is  important 
variableDe  script  ions  -  Descriptions  associated  to  variables.  The  order  is  important 
variables  Qualifiers  -  List  of  variable  qualifiers  indexed  by  variable  ID  in  a  map 


**  void  setMinAPValues ( int [ ]  values) 

Sets  the  minimum  for  action  points 

Parameters: 

values  -  the  minimum  action  point  values  in  the  same  order  as  action  point  labels 


**  void  setMaxAPValues ( int [ ]  values) 

Sets  the  maximum  for  action  points 

Parameters: 

values  -  the  maximum  action  point  values  in  the  same  order  as  action  point  labels 


**  void  initGUI ( j ava . lang . String  sideName, 
j ava . lang . String  userlD, 
j ava . lang . String  participantID, 
j ava . lang . String  sessionID, 
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j ava . lang . String  groupID, 
j  ava . util . Map< j  ava . lang . String, 
j ava . lang . Ob j ect>  parameters, 
j  ava . util . Collection<ca . lti . image  see . scenariov2 . 
coin2 . gen . components . AP>  interventions , 
variables Inf luenceOnAP, 
j  ava . util . Lis to  mutual Influences , 
j  ava . util . Lis t<>  condi tionalMutual Influence, 
j  ava .util. Lis t< j ava . lang . String>  collaborators , 
ca . lti . image  see . scenariov2 . coin2 . ui . 

callback . UlServerCallback  serverCallback) 

Initialize  the  main  GUI. 

Parameters: 

sideName  -  appended  to  the  title,  which  is  provided  by  the  scenario  as  a  parameter 
userlD  -  the  user  ID 

participantiD  -  the  participant  ID,  as  specified  at  the  beginning  of  a  mandate 
sessionlD  -  the  session  ID 
groupID  -  the  group  ID 

parameters  -  the  actual  scenario  parameters,  indexed  by  parameter  names 
interventions  -  the  list  of  interventions  for  the  current  user 
variableslnf  luenceOnAP  -  the  provenance  of  action  points,  index  by  variable 
mutual  Influences  -  the  list  of  mutual  influences  for  every  variable 

conditionalMutual Influence  -  the  list  of  conditional  mutual  influences  for  every  variable, 
collaborators  -  a  list  of  collaborators  with  the  current  participant. 
serverCallback  -  a  reference  to  callback  methods 


**  void  setMaxValues ( int [ ]  values) 

Set  the  max  values  for  variables 

Parameters: 

values  -  the  maximum  variable  values  in  the  same  order  as  variables  IDs 


**  void  setMinValues ( int [ ]  values) 

Set  the  min  values  for  variables 

Parameters: 

values  -  the  minimum  variable  values  in  the  same  order  as  variables  IDs 


**  void  setMinGreenValues ( int [ ]  values) 

Set  the  min  values  for  considering  a  variable  in  the  green  range 

Parameters: 

values  -  the  minimum  green  variable  values  in  the  same  order  as  variables  IDs 


**  void  setMaxGreenValues ( int [ ]  values) 

Set  the  max  values  for  considering  a  variable  in  the  green  range 

Parameters: 

values  -  the  maximum  green  variable  values  in  the  same  order  as  variables  IDs 


**  void  setMinOrangeValues ( int [ ]  values) 

Set  the  min  value  for  considering  a  variable  in  the  orange  range 

Parameters: 

values  -  the  minimum  orange  variable  values  in  the  same  order  as  variables  IDs 
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**  void  setMaxOrangeValues (int [ ]  values) 

Set  the  max  value  for  considering  a  variable  in  the  orange  range 

Parameters: 

values  -  the  maximum  orange  variable  values  in  the  same  order  as  variables  IDs 


**  void  setUncertaintyValues (int [ ]  values) 

Set  the  uncertainty  values  for  each  variable 

Parameters: 

values  -  the  uncertainty  values  for  variables,  in  the  same  order  as  variables  IDs 


**  void  setVisible (boolean  visible) 

Set  the  main  frame  visible  or  not 
Parameters: 

visible  - 


void  setTurn(int  turn) 
Set  the  current  turn 

Parameters: 

turn  -  the  current  turn 


**  void  setActionPoint ( int  actionPoint) 

Set  the  number  of  available  action  points. 

Parameters: 

actionPoint  -  the  number  of  available  action  points 


void  setVariables (int [ ]  variables) 

Set  the  variables'  value,  ordered  as  specified  with  the  "initLabels"  call 

Parameters: 

variables  -  the  variables  values,  in  the  same  order  as  variables  IDs 


**  void  endMandate ( j  ava . util . Map< j  ava . lang . String,  j  ava . lang . Integer> 

endVariablesValues ,  int  turn.  String  endStatus) 

Notify  the  main  user  interface  of  the  end  of  mandate,  providing  variables  values. 

Parameters: 

endVariablesValues  -  variable  values  index  by  variable  IDs 
turn  -  the  end  turn 

endStatus  0  the  status  at  the  end  of  a  mandate 


**  void  waitNextTurn ( ) 

Wait  for  the  "next  turn"  button  to  be  pressed 


int  getAP(int  index) 

Get  the  value  of  the  decision  made  by  the  user  for  the  given  action  point 

Parameters: 

index  -  the  index  of  action  point  value  that  should  be  retrieved,  as  specified  in  action  point 
labels. 

Returns: 
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int  getUnusedAP ( ) 

Returns  the  number  of  unused  Action  points 

Returns: 


int  getPrediction ( int  index) 

Get  the  value  of  the  prediction  made  by  the  user  for  the  given  variable 

Parameters: 

index  -  the  index  of  variable,  as  specified  in  order  by  variable  IDs 

Returns: 


int  getConfidence (int  index) 

Get  the  value  of  the  confidence  selected  by  the  user  for  the  given  variable 

Parameters: 

index  -  -  the  index  of  variable,  as  specified  in  order  by  variable  IDs 

Returns: 


**  void  addlnfoText (ca . lti . image  see . scenariov2 . coin2 . gen . components . 

TurnlnfoText  infoText,  int  turn) 

Add  info  text  with  the  provided  parameters. 

Parameters: 

infoText - 
turn  - 


**  void  initFeedbackScreen ( j ava . lang . String [ ]  variablelDs, 

j  ava . lang . String [ ]  variable Labe Is , 
j  ava . util . Lis t< j ava . lang . String> 
disabledVariables , 
j  ava . util . Map< j  ava . lang . String, 

j  ava  .util.  Lis  t<  j  ava  .  lang  .  String» 
variablesQualif iers , 
j ava . lang . String  actionPointID, 
int  endOfTurnFeedbackMode, 
int  predictionMode) 

Initialize  the  end  of  turn  feedback  screen  with  the  provided  variable  IDs  and  labels 

Parameters: 

variablelDs  - 
variableLabels  - 
disabledVariables  - 
variablesQualif iers  - 
actionPointID  - 
endOfTurnFeedbackMode  - 
predictionMode  - 

**  void 

waitFeedbackScreen ( j  ava . util . Map< j  ava . lang . String, j  ava . lang . Integer>  currentV 
alues , 

j  ava . util . Map< j  ava . lang . String, 
j  ava . lang . Integer>  previousValues , 
j  ava . util . Map< j  ava . lang . String, 
j  ava . util . List<ca . lti . image_sce . scenariov2 . 
coin2 . gen . components . Inf luenceValue>> 
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inf luenceValueMap, 
j  ava . util . Map< j  ava . lang . String, 

j  ava . lang . Integer>  predict ionValues , 
j  ava . util . Map< j  ava . lang . String, 

j  ava . lang . Integer>  actionPointsContributionMap) 
Wait  for  the  feedback  screen  to  be  closed  by  the  user 
Parameters: 
currentValues  - 
previousValues  - 
inf luenceValueMap  - 
predictionValues  - 
actionPointsContributionMap  - 

**  void  createEndDialog (j ava . lang . String  title, 

j ava . lang . String  imageFileName) 

Create  an  end  dialog  with  the  given  title  and  image  file  name 
Parameters: 

title  - 

imageFileName  - 


**  void  showEndDialog (boolean  visible) 

Show  or  hide  the  end  dialog 
Parameters: 

visible  - 


**  void  showEndDialog (boolean  visible, 

boolean  closeable) 

Show  or  hide  the  end  dialog 
Parameters: 

visible  - 

closeable  -  whether  the  end  dialog  is  closeable 


**  void  addEndSummaryVariableValues ( j ava . lang . String  label, 

float []  values) 

Add  variable  values  to  the  end  summary  dialog 
Parameters: 

label  - 
values  - 


**  void  showEndSummaryDialog ( ) 

Show  the  end  summary  dialog 


**  void  createTurnTransitionDialog ( j ava . lang . String  title, 

j ava . lang . String  imageFileName) 
Create  the  turn  transition  dialog  with  the  provided  title  and  image  file  name 
Parameters: 

title  - 

imageFileName  - 


**  void  showTurnTransitionDialog (boolean  visible. 
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boolean  fullscreen) 

Show/hide  the  turn  transition  dialog  and  sets  it  fullscreen  or  not 
Parameters: 

visible  - 
fullscreen  - 


**  void  showTurnTransitionDialog (boolean  visible) 
Show/hide  the  turn  transition  dialog 
Parameters: 

visible  - 


**  void  createTurnWaitDialog (j ava . lang . String  title, 

j ava . lang . String  imageFileName) 

Create  the  turn  wait  dialog  with  the  provided  title  and  image  file  name 
Parameters: 

title  - 

imageFileName  - 


**  void  showTurnWaitDialog (boolean  visible, 

boolean  fullscreen) 

Show/hide  the  turn  wait  dialog  and  sets  it  fullscreen  or  not 

Parameters: 

visible  - 
fullscreen  - 


**  void  showTurnWaitDialog (boolean  visible) 

Show/hide  the  turn  wait  dialog 
Parameters: 

visible  - 


**  void  waitDoneO 

Wait  for  the  user  to  shut  down  the  user  interface. 


**  void  addActionPoints ( j ava . lang . String  fromParticipant, 

int  nbPoints) 

Add  the  specified  amount  of  action  points  to  the  current  participant. 

Parameters: 

fromParticipant  -  the  participant  from  which  action  points  are  sent. 
nbPoints  -  the  number  of  action  points  sent 


U|- September  2010 


63 


D.  Quick  Start  Reference  Guide 


This  guide  gives  a  quick  overview  on  how  to  execute  various  programs  that  are  part  of  the  experimental 
platform,  and  describes  the  main  operations  that  will  lead  to  a  functional  executable  simulation  model. 

D.l  Walkthrough 

D.l.l  Single  User 

1)  Ensure  that  the  Java  executable  is  in  the  path  of  your  operating  system  (typically  0bin0  directory 
of  the  Java  runtime  environment); 

2)  Launch  the  scenario  editor  via  0CODEM_ScenarioEditor.bat0; 

3)  If  you  want  to  modify  an  existing  scenario,  choose  0File  /  Open0and  select  the  appropriate  file  in 
the  file  browser.  Otherwise,  start  by  adding  variables  and  action  points  to  your  scenario.  Do  not 
forget  to  add  instances  of  your  variables  and  action  points  via  the  0Scenario0tab; 

4)  Save  your  work  to  an  appropriate  0.cdm0file; 

5)  Execute  CODEM  by  double  clicking  on  the  scenario  file  that  you  just  saved.  If  0.cdm0  file 
extensions  are  not  associated  to  CODEM,  return  to  the  scenario  editor  and  choose  0Config  / 
Register  CDM  files. 0  Double  clicking  on  a  CDM  file  should  now  work  fine; 

6)  Once  you  are  finished  with  a  mandate,  press  0CTRL+ALT+X0  in  order  to  close  the  CODEM  user 
interface. 

D.l. 2  Multiple  Users  (Cooperative  or  Competitive) 

1)  Ensure  that  the  Java  executable  is  in  the  path  of  your  operating  system  (typically  0bin0  directory 
of  the  Java  runtime  environment); 

2)  Launch  the  scenario  editor  via  0CODEM_ScenarioEditor.bat0; 
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3)  If  you  want  to  modify  an  existing  scenario,  choose  BFile  /  OpenBand  select  the  appropriate  file  in 
the  file  browser.  Otherwise,  start  by  adding  variables  and  action  points  to  your  scenario.  Do  not 
forget  to  add  instances  of  your  variables  and  action  points  via  the  BScenarioBtab; 

4)  For  only  one  participant  (action  point),  specify  BlocalhostB  in  the  BHostB  parameter.  This 
participant  will  be  referred  to  as  Blocal.B  For  all  the  others,  enter  the  IP  address  of  the 
respective  computer  on  which  the  corresponding  user  will  be  located.  Those  participants  will  be 
referred  to  as  BremoteB; 

5)  Save  your  work  to  an  appropriate  B.cdmBfile; 

6)  On  the  computer  associated  to  every  remote  participant,  execute  BCODEM_RemoteService.batB 
This  will  enable  the  computer  to  start  a  user  interface  remotely,  as  requested  by  the  local 
participant.  There  is  no  need  to  start  this  service  on  the  computer  associated  to  the  local 
participant.  Also  note  that  once  the  service  is  launched,  there  is  no  need  to  start  it  again  every 
time  a  new  simulation  begins; 

7)  On  the  computer  associated  to  the  local  participant,  double  click  on  the  B.cdmBfile  that  contains 
the  scenario  information.  If  everything  is  configured  correctly,  this  should  launch  the  CODEM 
user  interface  on  local  computer,  and  one  instance  of  the  CODEM  user  interface  on  every 
remote  computer.  Otherwise,  error  messages  will  pop  up  indicating  what  went  wrong; 

8)  Once  a  mandate  is  over,  every  participant  has  to  press  BCTRL+ALT+XB  in  order  to  close  the 
CODEM  user  interface. 

D.2  Important  Files 

The  platform  contains  a  hierarchy  of  files  and  directories  that  are  of  crucial  importance  for  the  platform 
to  work  correctly.  Their  role  is  the  following: 

BconfigB  directory:  this  directory  contains  configuration  files  for  the  scenario  editor 
(BEditorConfig.xmlB)  and  the  variables  layout  (Blayout.xmlB).  You  can  modify  those  files  in  order 
to  configure  the  operation  of  the  editor  as  well  as  labels  in  the  platform; 

BdataB  directory:  this  directory  typically  contains  files  that  configure  the  experimental  platform 
(e.g.  images,  sound  files)  as  well  as  the  actual  CDM  simulation  scenario 
(BGeneratedScenario.cdmB); 

BlibB  directory:  this  directory  contains  every  Jar  file  that  supports  the  experimental  platform. 
You  should  not  directly  modify  files  contained  in  this  directory; 

BlogsB directory:  this  directory  contains  log  files  that  are  associated  to  every  single  mandate; 
BCODEM.exeB:  this  file  executes  the  experimental  platform  given  the  BGeneratedScenario.cdmB 
file  that  is  currently  located  in  the  BdataB  directory,  without  displaying  any  output  console; 
BCODEM.batB:  this  file  executes  the  experimental  platform  given  the  BGeneratedScenario.cdmB 
file  that  is  currently  located  in  the  BdataB  directory,  and  displays  an  output  console; 
BCODEM_RemoteService.batB:  this  file  executes  the  service  that  starts  a  main  user  interface  on 
a  remote  computer.  You  should  start  it  on  every  remote  computer  involved  in  a  collaborative  / 
competitive  mandate; 
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0CODEM_ScenarioEditor.bat0:  this  file  executes  the  scenario  editor.  By  default,  the  scenario 
editor  opens  an  empty  scenario.  You  can  specify  the  file  name  you  want  to  open  on  the 
command  line. 

D.3  Important  Operations  in  the  Experimental 
Platform 

Once  a  scenario  is  generated  by  following  the  steps  listed  in  the  previous  section,  a  simulation  can  be 
executed.  The  simulator  can  be  started  via  the  0CODEM.exe0file,  which  loads  a  default  scenario,  or  by 
double-clicking  on  a  CDM  file.  When  several  participants  are  involved  in  a  mandate,  do  not  forget  to 
start  0CODEM_RemoteService.bat0  on  every  remote  computer.  Once  the  main  user  interface  shows  up, 
the  0Situation0  tab  will  be  displayed.  Depending  on  the  game  mode,  other  tabs  will  be  available  in  the 
user  interface.  Some  might  be  disabled,  meaning  that  prior  operations  have  to  be  completed  before 
they  can  be  accessed.  For  example,  when  prediction  needs  to  be  entered  before  making  decisions,  the 
decision  tab  will  remain  greyed  out  until  the  0Done0  button  has  been  clicked  in  the  0Prediction0tab.  In 
the  0Relations0  and  0End  of  turn  feedback0  dialog,  you  can  observe  both  incoming  and  outgoing 
relations.  Use  the  right  mouse  button  in  order  to  switch  modes. 

The  placement  of  the  variables0labels  can  be  changed  through  by  the  user.  Hitting  the  0CTRL+E0  key 
switches  from  0normal0  mode  to  0editing0  mode.  In  editing  mode,  variables0  labels  can  be  moved 
around  the  user  interface  by  dragging  them  with  the  mouse.  The  main  dialog  can  also  be  resized;  for 
that  purpose,  simply  move  the  mouse  cursor  to  the  edge  of  the  dialog.  A  0resize0  cursor  will  appear. 
Then  press  the  left  mouse  button  and  drag  the  edge  of  the  dialog  to  the  desired  size.  Hitting  0CTRL+E0 
will  save  the  new  layout  and  size  to  a  file  (0config/layout.xml0),  which  will  be  reloaded  next  time  the 
experimental  platform  is  executed. 

In  order  to  refrain  participants  from  exiting  the  platform  inadvertently,  the  main  dialog  is  not  closable 
via  the  well-known  0X0  button.  Indeed,  the  0CTRL+ALT+X0  key  must  be  pressed  in  order  for  the  platform 
to  be  closed,  which  will  also  release  several  resources  and  close  open  files.  Log  files  will  also  be  written 
to  disk,  which  will  be  accessible  in  the  0logs0 directory.  Being  formatted  in  comma-separated  values,  log 
files  can  be  opened  in  Excel  or  with  any  other  software  that  supports  this  file  format. 

D.4  Troubleshooting  of  the  Experimental  Platform 

Ql:  The  platform  does  not  start  when  I  execute  the  0.exe0file.  What  should  I  do? 

Al:  Make  sure  that  the  Java  executable  is  in  your  0Path0  environment  variable.  If  it  is  the  case  but  the 
platform  still  does  not  start  correctly,  run  the  0.bat0  in  the  command  line  and  look  for  error  messages  in 
the  console. 
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Q2:  The  scenario  editor  does  not  behave  as  it  should,  what  is  happening? 

A2:  You  should  name  the  variables  and  action  points  using  only  letters  and  numbers.  Please  try  to  avoid 
symbols  and  space  characters  as  they  are  not  supported  in  XML  Ids.  You  can  keep  the  fancy  characters 
to  the  0abel0  parameter. 

Q3:  Remote  user  interfaces  do  not  show  when  I  start  the  simulator.  Why  is  that? 

A3:  You  should  first  check  if  the  Remote  Ul  Dispatch  Starter  Server  is  running  on  remote  computers,  and 
if  so  try  to  restart  it.  You  should  also  check  whether  you  specified  the  correct  IP  addresses  /  hostnames 
of  remote  computers.  If  all  of  this  is  correct,  try  to  deactivate  the  Windows  (or  Linux)  firewall  so  that  the 
server  ports  are  not  blocked  or  add  an  exception  to  your  firewall  configuration.  Otherwise,  see  the 
console  output  and  send  the  result  to  frioux(a)ltinfo.ca. 

Q5: 1  want  to  build  an  extension,  how  should  I  proceed? 

A5:  It  is  suggested  that  you  add  your  extensions  in  a  separate  Jar  file.  You  will  then  not  be  able  to  use 
the  executable  file,  but  you  can  definitely  use  the  ELbatEin  order  to  execute  the  platform.  Do  not  forget 
to  add  your  .jar  to  the  classpath.  You  can  create  your  extension  class  by  implementing  appropriate 
interfaces  and  using  available  Java  objects  with  the  specified  API,  located  in  CODEM.jar. 
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E.  From  Conceptual 

Representations  to  System 
Dynamics  Simulation 


In  order  to  build  a  generic  version  of  the  platform,  tools  that  are  part  of  the  IMAGE  project  were 
exploited.  CoGUI  was  used  to  represent  a  system  dynamics  model  using  agents,  and  the  generic  agent- 
based  simulator  is  used  as  a  simulation  engine.  CoGUI  is  an  all-purpose  knowledge  representation  tool. 
Therefore,  it  allows  for  the  representation  of  any  kind  of  knowledge  using  concepts  linked  by  relations. 
However,  in  order  for  a  set  of  graphs  to  be  of  any  use,  they  need  to  be  minimally  structured  such  that  a 
graph  interpreter  will  be  able  to  figure  out  what  to  generate,  in  terms  of  Java  source  code  and  XML 
elements,  when  it  encounters  a  given  concept  /  relation  configuration.  The  following  sections  will 
introduce  how  to  represent  knowledge  in  CoGUI,  and  more  specifically  how  to  represent  an  agent-based 
simulation  scenario.  Then,  the  source  code  and  XML  scenario  generation  process  will  be  presented  for 
the  generic  agent-based  simulator.  The  final  section  will  introduce  entities  that  need  to  be  described  in 
conceptual  graphs  in  order  to  build  a  system  dynamics  simulation. 

E.lConceptual  Representation  with  CoGUI 

Being  an  all-purpose  knowledge  representation  tool,  CoGUI  allows  for  any  kind  of  knowledge  to  be 
conveyed  in  a  graph.  The  first  step  in  building  a  conceptual  graph  with  CoGUI  is  to  define  a  vocabulary, 
or  0concept  type  hierarchy. 0  The  vocabulary  is  actually  a  hierarchy  that  defines  a  set  of  concepts  that 
will  be  allowed  being  added  to  a  conceptual  graph.  A  similar  hierarchy  has  to  be  defined  for  relations 
that  link  two  or  more  concepts  together.  In  Figure  33,  the  0relation  type  hierarchy0is  displayed  on  the 
upper  left,  the  0concept  type  hierarchy0  is  shown  on  the  upper  right  and  the  instance  of  a  conceptual 
graph  that  uses  the  actual  relation  and  concept  hierarchies  is  shown  at  the  bottom.  For  more  details  on 
the  notation,  please  refer  to  the  CoGUI  user  guide. 
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Figure  33  -  Example  of  a  conceptual  graph  in  CoGUI 


E.2Agent-Based  Simulation  Using  Conceptual 
Representations 

A  custom  agent-based  simulator  was  developed  and  integrated  in  IMAGE.  It  can  simulate  virtually  any 
kind  of  scenario  that  involves  autonomous  entities.  Depending  on  the  role  of  an  entity,  it  will  be  one  of 
the  following  types:  agent,  patient  or  decor.  Agents  own  static  and  dynamic  properties  and  they  can  act 
on  their  environment  through  behaviours  that  are  activated  either  by  motivations  (condition  that  is 
verified)  or  via  reflexes  (change  of  a  dynamic  property).  Patients  also  own  static  and  dynamic  properties 
but  they  can  only  act  on  their  environment  through  behaviours  that  are  activated  via  reflexes.  Decors, 
on  the  other  hand,  only  own  static  properties  and  they  cannot  act  on  their  environment  nor  be 
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modified.  Behaviours  associated  to  agents  and  patients  manipulate  dynamic  properties  at  every  time 
step  in  order  to  update  entities.  This  is  where  the  actual  user-written  source  code  that  defines  how  and 
when  an  entity  will  modify  its  environment  is  located. 

An  original  contribution  of  IMAGE  is  the  complete  model  transformation  infrastructure  that  allows 
conceptual  representations  to  be  transformed  to  an  actual  executable  scenario  that  is  implemented 
using  the  custom  agent-based  simulator.  For  that  purpose,  an  entire  vocabulary  and  semantics  was 
defined,  resulting  in  conceptual  graphs  that  can  be  interpreted  by  the  scenario  transformer.  Figure  34 
details  the  scenario  generation  process  that  is  triggered  by  a  user  who  has  defined  a  scenario  via  well- 
constructed  conceptual  graphs.  In  order  to  trigger  the  scenario  generation  process,  right  click  on  a 
scenario  graph  located  in  the  0Scenarios0  category  and  choose  the  ^Generate  scenario 0  item.  Note  that 
in  addition  to  Java  skeleton  classes  that  define  entities,  properties,  behaviours  and  stimulations,  an  XML 
scenario  file  is  built  that  contains  values  associated  to  properties  and  scenario  configuration  parameters. 
For  more  details  on  how  to  build  a  scenario  using  the  process  described  in  this  section,  please  refer  to 
the  scenario  generator  user  guide. 
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Source  code  is  generated 
from  templates  with  the 
Apache  Velocity  toolkit  for 
static  &  dynamic 
properties,  entity 
components,  simulation 
cycles  and  behaviours 


The  user  writes  his  code  in 
implementation  classes 
using  Eclipse 


Source  code  is  compiled 
with  an  automatic  build 
using  an  Ant  script 


The  simulator  loads  the 
XML  scenario  file,  which 
contains  all  necessary 
information  for  initializing 
the  simulation  state  and 
instantiating  static  & 
dynamic  properties, 
behaviours  and  simulation 
cycles 


Scenario  Generator 
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tr 
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Contains  ;  Java  XML  Binding 
objects 
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An  XML  file  is  created  via 
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Figure  34  -  Scenario  generation  process  in  IMAGE 


E.3Agent-Based  System  Dynamics  Simulation 

The  current  mandate  is  to  develop  an  experimental  platform  that  will  study  how  humans  deal  with 
complex  systems  /  situations.  For  that  purpose,  the  generic  agent-based  simulator  developed  as  part  of 
IMAGE  is  used.  Similar  to  another  knowledge  representation  and  simulation  program  called  the 
Sensitivity  Model  (Vester,  2007),  the  experimental  platform  uses  a  system  dynamics  simulation 
formalism  in  order  to  perform  calculations  on  the  modeled  complex  system.  In  fact,  the  current 
platform  is  based  on  a  model  that  contains  variables  linked  by  mutual  influence  relations,  and  action 
points  that  are  allocated  by  a  user  to  various  interventions  in  order  to  influence  the  variables.  One 
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additional  requirement  of  the  experimental  platform  is  that  the  user  should  not  have  to  write  any  code 
in  order  for  the  resulting  scenario  (generated  code  and  XML  configuration  file)  to  be  functional. 
Fortunately,  the  generic  agent-based  simulator  of  IMAGE  was  designed  such  that  it  is  possible  to 
execute  behaviours  on  child  types,  thanks  to  inheritance  of  entities  types.  Finally,  the  experimental 
platform  must  create  logs  of  events  and  user  behaviours  in  order  to  gain  insights  into  the  sensemaking 
and  decision  making  process  of  participants. 

At  the  functional  level,  CoGUI  is  started  via  the  0CoGUI.bat0file.  A  set  of  conceptual  graphs  is  contained 
in  files  that  have  the  0.cogxml0  extension.  You  can  either  load  a  complete  previously  built  set  of  graphs 
or  start  of  a  new  scenario  from  a  template  by  loading  the  file: 

0scenario/COINScenario_template.cogxml0 

The  latter  file  contains  the  basic  conceptual  structures  that  are  needed  in  order  to  generate  a  fully 
functional  complex  situation  scenario  at  the  simulation  level. 

The  set  of  conceptual  graphs  that  model  a  complex  situation  is  composed  of  several  0fixed0  graphs  that 
should  not  be  modified  by  a  scenario  developer.  They  are  clearly  identified  in  the  graphs  hierarchy  that 
is  available  in  CoGUI  (with  the  0do  not  touch0  mention).  On  the  other  hand,  the  graph  hierarchy  has  to 
contain  one  0VariableAgent0 graph  for  each  defined  variable,  and  one  0ActionPoint0  agent  for  each  set 
of  interventions  that  are  available  for  a  given  participant.  Figure  35  shows  a  sample  hierarchy  of 
conceptual  graphs  that  define  nine  variables  (V1-V9)  and  two  potential  participants  (ActionPointBlue 
and  ActionPointRed).  The  0AbstractAgents0  category  contains  parent  graphs  that  define  the  structure  of 
actual  agent  instances,  which  can  be  ActionPoints,  Variables,  CustomEvents  and  InfoText.  One  graph  is 
defined  for  every  variable  and  action  point,  whereas  all  info  text  and  custom  events  are  added  to  the 
same  graph.  Moreover,  instances  of  variables  and  action  points  are  declared  in  the  0Scenario0 
conceptual  graph,  as  well  as  all  the  parameters  that  are  used  to  configure  the  content  of  the  actual  user 
interface  with  which  participants  will  have  to  interact. 
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EM  Comprehension 
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Figure  35  -  Conceptual  graph  hierarchy  from  the  experimental  platform 


Conceptual  graphs  that  define  agents0behaviours  (category  ^Description  of  Behaviours0)  should  not  be 
modified  by  the  user,  so  is  their  scheduling  in  the  scenario  graph.  Behaviours  are  configured  to  be 
executed  at  appropriate  moments  during  the  simulation,  and  they  have  been  implemented  such  that  a 
scenario  designer  can  add  as  many  variables  and  participants  as  he  wants.  The  layout  of  the  user 
interface  changes  according  to  the  number  of  variables  and  action  points,  and  the  platform  supports  the 
distribution  of  participants  over  a  local  area  network. 

In  terms  of  inner  workings,  the  behaviours  have  the  following  roles: 

ActionPointDispatch  (on  ActionPoint  agents):  the  user  interface  is  updated  to  the  current 
variables  values  for  a  given  participant  and  the  behaviour  waits  until  the  participant  clicks  the 
0next  turn0  button; 

ActionPointUpdate  (on  ActionPoint  agents):  the  number  of  available  action  points  is  updated 
for  a  given  participant; 

DisplaylnfoText  (on  InfoText  agent):  the  info  texts  that  need  to  be  displayed  during  the  current 
turn  are  retrieved  and  sent  to  the  main  user  interface; 

ExecuteEvents  (on  CustomEvent  agent):  custom  events  are  executed  if  their  execution 
condition  is  verified.  Variables  are  updated  accordingly; 
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Influence  (on  Variable  agents):  the  influence  of  variables  on  other  variables  (delayed  or  not)  is 
calculated  and  values  are  accumulated  in  an  appropriate  data  structure.  Variables  are  not 
modified  at  this  time; 

Integration  (on  Variable  agents):  the  variable  is  modified  according  to  the  accumulated  values 
calculated  by  the  0influence0  behaviour. 

Finally,  behaviours  are  scheduled  in  the  following  sequence: 


-No- 


(?^  Start  j\ 


Before  turn 


I 


Execute  events 
before 


I 


Display  InfoText 


Win/lose?  jx 


Mandate  over 


For  each  variable 


— 

After  turn 

Execute  events 
after 


Variable 

integration 


ActionPoint 

update 

For  each  action  point 

For  each  variable^^ 

Variable  influence 

ActionPoint 

J 

dispatch 

For  each  action  point 


Figure  36  -  Sequence  of  behaviours  executed  in  the  custom  agent-based  simulator 


The  sequence  starts  with  an  initial  simulation  state  that  is  loaded  from  an  XML  scenario.  The  EBefore 
turn0  method  is  executed  that  is  owned  by  the  main  simulation  cycle.  Then,  behaviours  that  are 
associated  to  every  instantiated  agents  are  executed  with  the  order  specified  in  Figure  36.  The  0After 
turn0  method,  associated  to  the  main  simulation  cycle,  is  executed  after  the  execution  of  every 
behaviour.  This  includes  the  evaluation  of  winning  and  losing  conditions.  When  either  one  of  those 
conditions  is  true,  the  mandate  is  over.  Otherwise,  the  simulation  cycle  continues  to  the  next  turn. 
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